/* ============================================================================ tokens.css ยท the marketing site's measurements, in one place WHAT THIS FILE IS design.css is the design system: every colour, every component, every shape the product wears. It is correct, and this file does not replace any of it and does not redefine a single token it declares. It adds one thing design.css does not have: a set of numbers for the marketing site on a phone, named, so that "make the headings smaller" is one value in one place instead of a hunt through twenty pages. WHY A SEPARATE FILE Because these are the numbers most likely to be argued about and changed, and a file you can read top to bottom in a minute is a different thing to maintain than a very large one. Two other stylesheets here already add to :root the same way, so this is the established shape in this project rather than a new idea. THE NAMESPACE IS THE BOUNDARY Every token here begins --mk-, which is the marketing site's prefix. The console and the portals use different prefixes and this file is not loaded on any of them. A change to a marketing measurement therefore cannot move a screen someone is working in. That is the whole reason for the prefix, and the reason this file is not loaded product-wide. FLAT NUMBERS, NOT clamp(), ON A PHONE This is the one decision worth explaining, because it looks backwards. design.css sizes its marketing type with clamp(min, vw, max). Resolved at a 390px viewport, 31 of the 34 clamps in the marketing range land on their minimum: 6vw of 390px is 23.4px, which is under a 40px floor, so the floor is what ships. The fluidity is real between roughly 700px and 1100px and it is decorative below that. A flat number inside a breakpoint says out loud what was already happening, and it is the only form you can read a value off and trust. Fluidity stays where it works: above the breakpoint, in the clamps design.css and mobile.css already carry. TWO WIDTHS, AND 760px IS NOT A NEW NUMBER The base block is the desktop value. The override is 760px and below. 760px is the marketing site's existing mobile boundary: mobile.css already switches .desktop-only, the side gutter and the centred section heads at exactly that width, and design.css turns on its sticky bottom bar there. design.css's own 640px boundary belongs to the console's token layer, and the console is not what this file governs. One boundary for marketing, and it is a boundary already in the project. HOW TO USE A TOKEN Spend it inside a phone query, next to the declaration it replaces: @media (max-width:760px){ .mk-h1,.hero4 h1{font-size:var(--mk-t-hero);line-height:var(--mk-lh-hero)} } The desktop declaration is left alone. The base values below are copied from what ships on desktop today, so a var() spent outside a phone query resolves to a real number and is a no-op rather than a surprise. READ DESIGN.md FIRST. It carries the rules these numbers serve, the reasoning behind each one, and the decisions in design.css that must not be broken. ========================================================================= */ :root{ /* ---- TYPE --------------------------------------------------------------- Seven sizes. A marketing page needs a hero line, a section heading, a card title, a lede, body copy, a caption and a label, and it does not need an eighth. Base values are design.css's own expressions, verbatim. */ --mk-t-hero:clamp(2.5rem,6vw,4.4rem); /* the one big line on the page */ --mk-t-h2:clamp(1.7rem,3.5vw,2.6rem); /* a section heading */ --mk-t-h3:1.5rem; /* a card title, never a section heading */ --mk-t-lede:clamp(1.08rem,2vw,1.32rem); /* the sentence under a heading */ --mk-t-body:15px; /* every paragraph */ --mk-t-meta:13px; /* captions, trust lines, footer links */ --mk-t-eyebrow:12.5px; /* the small uppercase label */ /* ---- LINE HEIGHT ------------------------------------------------------- 1.1 on display is a CEILING, not a target. Three display rules in design.css are already tighter than it, at 1.02 and 1.04. Raising them to 1.1 would make the page taller, which is the opposite of the point, so the hero keeps its own token and its own tighter value. */ --mk-lh-display:1.1; --mk-lh-hero:1.04; --mk-lh-body:1.5; /* ---- SPACE ------------------------------------------------------------- */ --mk-gutter:var(--s4); /* the page's side padding */ --mk-pad-section:clamp(48px,8vw,104px); /* the air above and below a section */ --mk-pad-card:var(--s4); /* inside an ordinary card */ --mk-pad-card-lg:var(--s5); /* inside a card that holds a list */ --mk-gap:var(--s3); /* between cells of a grid */ --mk-stack:32px; /* between stacked blocks in a section */ /* ---- MEASURE ---------------------------------------------------------- How long a line is allowed to get. Every base value is a cap the matching marketing component already carries, so nothing here invents a measure. */ --mk-measure-hero:16ch; /* the dark hero's own cap on its headline */ --mk-measure-display:18ch; /* a one-sentence statement */ --mk-measure-lede:36ch; /* the shipped lede cap */ --mk-measure-prose:54ch; /* the widest measure the marketing system ships */ --mk-measure-cell:44ch; /* a paragraph inside a card */ /* ---- SHAPE AND CONTROLS ------------------------------------------------ Two of these are aliases at desktop width on purpose, and an alias is only allowed when the second name carries a decision the first one cannot. --mk-r-card says: a marketing card uses the large radius. It never uses the extra-large one. That matters because the extra-large radius is 22px at every width, including on a 346px-wide phone card with 14px of padding, where the corner is wider than the padding. The extra-large token is left exactly as it is, because the product's bottom sheet depends on it; the marketing side simply stops reaching for it. --mk-btn-h says: on a marketing page the tap floor is also the ceiling. 48px with a mouse, 44px with a thumb, and nothing taller for effect. */ --mk-r-card:var(--r-lg); --mk-btn-h:var(--tap); --mk-bar-h:56px; /* a sticky bottom action bar: a 44px control with 6px above and below */ --mk-bar-clear:calc(var(--mk-bar-h) + env(safe-area-inset-bottom,0px)); /* ---- TWO GATES -------------------------------------------------------- Numbers that answer a yes or no question rather than setting a size. --mk-cell-min is the width below which a two-up cell can no longer carry a SENTENCE. At a 390px viewport the content column is 346px, a two-up cell with a 10px gap is 168px, and 14px of padding each side leaves 140px inside it, which is about sixteen characters at 15px. Chips, counts and one-or-two-word labels are not sentences and have no minimum: they stay two up at every width. This gate exists only to stop a paragraph being poured into a column that cannot hold one. --mk-table-col-min is the column width that keeps a table readable while it scrolls sideways inside its frame. It is the number design.css already uses for the same job on the schedule grid. */ --mk-cell-min:150px; --mk-table-col-min:88px; /* ---- MOTION BUDGET ---------------------------------------------------- No new easing curve. design.css already publishes one and it is the only curve a marketing page should use; a second would be two names for one thing. What was missing was durations, which were written as literals in forty-odd places. These four are the values already in the file, named, so the next thing that moves picks one instead of inventing a fifth. --mk-move is the amplitude of a reveal. Anything that travels further than this on scroll reads as decoration rather than arrival. */ --mk-dur-1:120ms; /* a press, a tap state */ --mk-dur-2:180ms; /* a hover, a chip, an accordion */ --mk-dur-3:280ms; /* a panel, a sheet, a bar arriving */ --mk-dur-4:600ms; /* a section revealing on scroll */ --mk-move:12px; } /* ============================================================================ THE PHONE. 760px and below. Every value here is flat. Read them off and trust them. ========================================================================= */ @media (max-width:760px){ :root{ /* TYPE. The bands these serve are in DESIGN.md section 1.1: body 15 to 16, headings 24 to 28, hero 30 to 34. 32px on the hero is not a guess. Sixteen of the twenty pages that use the marketing h1 already set their own size by hand and they landed between 28.8px and 33.6px; eight of them chose exactly 32px. This token is the number the site already converged on, written down once so the next page does not have to be talked into it. The card title sits at 19px, between body and heading, because that is the tier it occupies. A card title the same size as the section heading above it flattens the hierarchy, and three of them are exactly that size today. See DESIGN.md 2.1 for the full reasoning. */ --mk-t-hero:32px; --mk-t-h2:25px; --mk-t-h3:19px; --mk-t-lede:16px; --mk-t-body:15px; --mk-t-meta:13px; --mk-t-eyebrow:12px; --mk-lh-display:1.1; --mk-lh-hero:1.04; --mk-lh-body:1.4; /* SPACE. 22px is the gutter the marketing site already ships on a phone. 40px is the section padding it already computes at 390px, written flat so it stops climbing to 56px on a larger phone, which is over the ceiling. 14px of card padding is 20px cut by 30 per cent, and it is already the padding on four other cards in the system, so it has a precedent in the file rather than being a new opinion. 12px between stacked blocks replaces 20px, which does not sound like much until you count the fifty or so section heads it is spent on. */ --mk-gutter:22px; --mk-pad-section:40px; --mk-pad-card:14px; --mk-pad-card-lg:16px; --mk-gap:10px; --mk-stack:12px; /* MEASURE. On a phone the gutter IS the measure. A 346px column at 15px is already a comfortable line, so a ch cap on top of it only makes the line shorter than the screen and the page taller. Display type keeps its cap, because a statement wants to break after a few words. If you are tempted to put a ch cap back on a phone: open the page at 390px first. If the lede is visibly narrower than the paragraph under it, the cap is the reason. */ --mk-measure-lede:none; --mk-measure-prose:none; --mk-measure-cell:none; /* SHAPE AND CONTROLS. Flat here, not aliased, and this is deliberate. The tokens they alias at desktop width change at 640px, not 760px, so leaving them as aliases would make a card in the 641 to 760 band carry a 16px corner and a button a 48px height while this file's own documented phone values say 12px and 44px. Declaring them flat makes the stated phone value true across the whole band this file calls the phone. */ --mk-r-card:12px; --mk-btn-h:44px; } } /* ============================================================================ ONE RULE, AND WHY A FILE OF MEASUREMENTS HAS A RULE IN IT Two rules in design.css sit in the same media query at the same specificity: .mk-wrap{padding-left:22px;padding-right:22px} .mk-section{padding: 0} The second is the `padding` shorthand, so it expands to all four sides and resets the side padding the first one set. Most marketing pages put both class names on one element, and on those elements the side gutter resolves to zero. The gutter is the first token in this file, so this file is where it gets to be true. One rule, four lines, longhands only, and it is the token proving itself rather than a value nobody can see. This rule can be deleted the day design.css writes that declaration as padding-top and padding-bottom instead of the shorthand. Until then it is load-bearing, and it only works because this file loads after design.css. Nothing loaded after this file may set .mk-wrap's side padding. ========================================================================= */ @media (max-width:760px){ .mk-wrap{ padding-left:max(var(--mk-gutter),env(safe-area-inset-left,0px)); padding-right:max(var(--mk-gutter),env(safe-area-inset-right,0px)); } } /* ============================================================================ SPENDING THE TOKENS. 760px and below. Everything above this line is a set of names. This is where they become the sizes on a phone, and it is the change the tokens existed for. It is deliberately short. Seven type rules, a gutter, a section, a card and a line height. If this block grows past about thirty declarations, something is being solved here that belongs in a component. WHY THIS CAN WIN WITHOUT !important Twelve pages used to set the hero size as an inline style attribute, which outranks any stylesheet rule that is not !important. Those attributes were removed in the same change that added this block, which is why the token can reach them now. If a hero ever looks wrong again, check for an inline font-size on the h1 before adding weight here. ========================================================================= */ @media (max-width:760px){ /* TYPE. The bands: body 15 to 16, headings 24 to 28, hero 30 to 34. */ .mk-h1,.hero4 h1{font-size:var(--mk-t-hero);line-height:var(--mk-lh-hero)} .mk-h2{font-size:var(--mk-t-h2);line-height:var(--mk-lh-display)} .mk-statement{font-size:var(--mk-t-h2);line-height:var(--mk-lh-display)} .mk-lede,.hero4 .lede{font-size:var(--mk-t-lede);line-height:var(--mk-lh-body)} .mk-eyebrow{font-size:var(--mk-t-eyebrow)} body{font-size:var(--mk-t-body);line-height:var(--mk-lh-body)} /* A card title is a tier below a section heading. Three of them were exactly the same size as the heading above them, which flattens the hierarchy. */ .mk-door h3,.mk-plan__name,.mk-feature h3{font-size:var(--mk-t-h3)} /* SPACE. The section padding is flat so it stops climbing to 56px on a larger phone, which is over the owner's 48px ceiling. */ .mk-section{padding-top:var(--mk-pad-section);padding-bottom:var(--mk-pad-section)} /* SHAPE. A 22px corner inside 14px of padding on a 346px card reads as a mistake. --mk-r-card is the marketing card's radius and it does not touch --r-xl, which the product's bottom sheet depends on. */ .mk-plan,.mk-door{border-radius:var(--mk-r-card);padding:var(--mk-pad-card-lg)} /* MEASURE. On a phone the gutter is the measure. A ch cap on top of it only makes the line shorter than the screen and the page taller. */ .mk-lede,.mk-head .mk-lede{max-width:var(--mk-measure-lede)} }