/* Mikko Koivunalho Oy -- web design tokens. * * Custom properties ONLY. This file styles no element and imposes no layout, so * a static marketing site, a Dancer2 application and a notice service can all * take it without inheriting each other's opinions. Element defaults, if wanted, * live in the optional mkoy-base.css beside it. * * THE SOURCE IS POLMAI, NOT THE DECK PALETTE * ------------------------------------------ * ../brand-style-guide.md section 2 is the palette for DECKS AND PRINT: a deep * navy on white paper. The SCREEN palette is Polmai's -- grey page, dark bar, * one blue accent -- because that interface works, a customer has used it and * approved it, and it was built for dense tabular data read all day rather than * for slides read across a room. * * So MKOY has two palettes, on purpose, and section 7 of the guide says so. * That is a deliberate split rather than drift. A screen and a printed page are * different media with different ambient contrast, and treating them as one is * how you get either a washed-out deck or an interface that glares. * * WHAT CHANGED FROM POLMAI AS SHIPPED * ----------------------------------- * Almost nothing, and every change is a measured accessibility fix, not taste: * * 1. --border is NEW. Polmai bounds its form controls with --line #b4b4b4, * which measures 1.47 against the page. WCAG 1.4.11 requires 3:1 for the * boundary of anything a person has to find and click. * 2. --caution-* is NEW. Polmai has no amber, so "look at this" and "this * failed" were the same red and the interface could not tell them apart. * 3. --error-* is Polmai's --warn, renamed. It was already red and already * passing; only the name was wrong, because a warning and a failure are * different things and one token cannot be both. * * EVERY CONTRAST CLAIM HERE IS MEASURED, NOT ASSERTED. * Run ./check-contrast.py to reproduce them. Change a colour and run it again -- * that is why it sits next to the palette instead of in a document. * * NO DARK THEME YET, on purpose. See the block at the bottom for how to add one * later without changing anything that consumes these names. */ :root { /* ---- Surfaces ---------------------------------------------------------- * Polmai's, unchanged. The grey page with lighter panels floating on it is * what makes dense tables readable: a white page behind white table rows has * no edge between them. --field is white because that is what an input must * be -- the one surface a person types into should never have to be guessed * at. */ --mkoy-bg: #d9d9d9; --mkoy-panel: #f4f4f4; --mkoy-field: #ffffff; /* ---- Text -------------------------------------------------------------- */ --mkoy-ink: #1c1c1c; /* 12.07 on bg, 15.49 on panel -- AAA */ --mkoy-muted: #5c5c5c; /* 4.74 on bg, 6.08 on panel -- AA */ /* ---- Lines, and why there are two -------------------------------------- * THE ONE ACCESSIBILITY DEFECT IN POLMAI AS SHIPPED, and the reason these are * two tokens rather than one. * * --hairline is Polmai's --line: table rules, dividers, decoration. It * measures 1.47 against the page, which is FINE for decoration -- WCAG * exempts it -- and is not fine for anything else. * * --border is for the boundary of a control a person has to find and click: * input, select, textarea, the outline of a secondary button. WCAG 1.4.11 * requires 3:1 there. Polmai uses --line for its form fields today, so every * text input in the application is bounded at 1.47 and is effectively * edgeless for a good many readers. * * Do not swap one for the other to "tidy up". They encode different rules. */ --mkoy-hairline: #b4b4b4; /* decoration only. 1.47 on bg -- exempt */ --mkoy-border: #757575; /* 3.26 on bg, 4.19 on panel, 4.61 on field */ /* ---- The top bar ------------------------------------------------------- * A dark band is its own small colour scheme, so text and links on it need * their own tokens: ink and accent are both unreadable there. This is the * nearest thing to a second theme the system has today, and getting it wrong * is how a navigation bar ends up with invisible links. */ --mkoy-bar: #3a3a3a; --mkoy-bar-ink: #f0f0f0; /* 9.98 on bar -- AAA */ --mkoy-bar-link: #cfe3f2; /* 8.62 on bar -- AAA */ /* Two more, because a dark band needs its own muted and its own border and * cannot borrow the page's. Both are measured fixes to Polmai as shipped: * its "none selected" grey is #9a9a9a at 4.04, which FAILS AA for body text, * and the outline on its log-out button is #6a6a6a at 2.10, which FAILS * 1.4.11. Both are the kind of miss that only a measurement finds -- they * look fine, and they are unreadable to somebody they were not designed by. */ --mkoy-bar-muted: #b8b8b8; /* 5.73 on bar -- AA */ --mkoy-bar-border: #8a8a8a; /* 3.29 on bar -- clears 1.4.11 */ /* Hover on anything sitting on the bar, including the user menu that hangs * off it. LIGHTER than the bar so the pointer has something to land on, and * no lighter than this: the note under a menu item is --mkoy-bar-muted, and * against #4a4a4a -- the value this replaced -- it measured 4.47, which is * under AA for text that size. #464646 puts it back to 4.76. A hover state is * still text somebody is reading. */ --mkoy-bar-hover: #464646; /* bar-muted 4.76, bar-ink 8.28 -- AA */ /* ---- Accent ------------------------------------------------------------ * One accent, Polmai's. A single light theme does not need the deck * palette's bright/deep pair: this one measures 5.02 on the page and 6.45 on * a panel, so it carries links, headings and button fills by itself. The * "bright" variant is --mkoy-bar-link above, doing the job a lightened accent * actually exists for -- sitting on a dark surface. */ --mkoy-accent: #1f5c8b; /* 5.02 on bg, 6.45 on panel -- AA */ --mkoy-on-accent: #ffffff; /* 7.09 on accent -- AAA */ /* ---- Status, three tokens each ----------------------------------------- * Polmai's callout pattern made explicit: a line colour, a pale tint to fill * the box, and an ink dark enough to read on that tint. Polmai already does * this for errors and notices and it already passes -- naming it is what lets * a second product copy it correctly instead of approximating it. * * Colour is never the only signal. A red box still needs the word "Error" in * it (WCAG 1.4.1): roughly one man in twelve cannot separate this red from * this amber, and nobody at all can hear a colour read aloud. */ /* ERROR -- this failed and something must be done about it. */ --mkoy-error: #8b2f1f; /* 5.89 on bg -- AA. Polmai's --warn, renamed */ --mkoy-error-bg: #f6dcd7; --mkoy-error-ink: #5c1f13; /* 9.72 on error-bg -- AAA */ --mkoy-on-error: #ffffff; /* 8.32 on error -- AAA */ /* CAUTION -- look at this, but nothing is broken. NEW. * * A deeper amber than the deck palette's #C9781A, and the grey page is the * reason: #C9781A measures 2.41 against #d9d9d9 and would fail as a rule or a * border. On the guide's white paper it is fine. About one stop of contrast * is the price of a grey background, and this is where it gets paid. */ --mkoy-caution: #a4640f; /* 3.37 on bg -- clears 3:1 for rules and borders */ --mkoy-caution-bg: #f8e6cf; --mkoy-caution-ink: #6b3d08; /* 7.50 on caution-bg -- AAA */ /* INFO -- neutral, worth reading. Shares the accent hue deliberately: it is * the same "the system is talking" voice, not a third colour to learn. */ --mkoy-info: #1f5c8b; --mkoy-info-bg: #dde9f2; --mkoy-info-ink: #14364f; /* 10.19 on info-bg -- AAA */ /* ---- Focus ------------------------------------------------------------- * Its own token even though it currently equals the accent, because the two * have different jobs and will diverge: an accent has to look right, a focus * ring has to be findable on whatever it lands on. Sharing one name is how a * focus ring quietly disappears the day somebody lightens the accent. */ --mkoy-focus: #1f5c8b; /* 5.02 on bg -- clears 3:1 */ /* ---- Typography -------------------------------------------------------- * Polmai's sans stack. The mono stack is the guide's: Polmai has no mono use * today and a notice service showing machine-readable JSON will. */ --mkoy-font-sans: system-ui, -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; --mkoy-font-mono: "Cascadia Code", "JetBrains Mono", "SF Mono", Consolas, "Liberation Mono", monospace; /* Polmai renders at 15px/1.5. Expressed in rem here and anchored so the * result is identical at a default 16px root -- 0.9375rem IS 15px -- but a * reader who has raised their browser's default font size gets the whole * scale raised with it. A px scale silently ignores that preference, and it * is the setting people with low vision actually use. */ --mkoy-text-xs: 0.8125rem; /* 13px */ --mkoy-text-sm: 0.875rem; /* 14px */ --mkoy-text-base: 0.9375rem; /* 15px -- Polmai's body size */ --mkoy-text-lg: 1.0625rem; /* 17px */ --mkoy-text-xl: 1.25rem; /* 20px */ --mkoy-text-2xl: 1.5rem; /* 24px */ --mkoy-text-3xl: 1.875rem; /* 30px */ --mkoy-weight-body: 400; --mkoy-weight-emphasis: 600; --mkoy-weight-heading: 700; --mkoy-leading-tight: 1.25; --mkoy-leading-body: 1.5; /* Polmai's */ /* ---- Space and shape --------------------------------------------------- * A small scale, deliberately: enough to lay out a form consistently, too few * steps to invent a layout system from. Layouts stay unshared until there is * a second real consumer to generalise from. */ --mkoy-space-1: 0.25rem; --mkoy-space-2: 0.5rem; --mkoy-space-3: 0.75rem; --mkoy-space-4: 1rem; --mkoy-space-6: 1.5rem; --mkoy-space-8: 2rem; --mkoy-radius: 3px; /* Polmai's */ --mkoy-radius-lg: 6px; } /* --------------------------------------------------------------------------- * ADDING A DARK THEME LATER * * Deliberately absent. Nothing that consumes these names will have to change * when it arrives, which is the whole reason the names above are semantic * (--mkoy-ink, --mkoy-panel) rather than literal (--mkoy-grey-88). * * When the time comes, three things and no more: * * 1. Redefine ONLY the colour tokens, in two blocks that must stay identical: * * @media (prefers-color-scheme: dark) { * :root:not([data-mkoy-theme="light"]) { ... } * } * :root[data-mkoy-theme="dark"] { ... } * * Both are needed. The media query alone cannot be overridden by somebody * who prefers light inside a dark OS; the attribute alone ignores the * system setting for everyone who never made a choice. Type, space and * shape are not theme-dependent and must NOT be repeated in either. * * 2. Re-enable the dark half of check-contrast.py, removed along with the * theme. It carried a check the eye will not do for you: that those two * blocks agree. If they drift, a reader with a dark OS and no explicit * choice sees a different palette from one who picked dark, and nobody * would think to look for it. * * 3. Watch the pairs that FLIP rather than lighten. On a dark surface white * stops being the right label colour on a filled control well before it * looks wrong -- which is why --mkoy-on-accent is a token at all instead * of being written #fff wherever a button happens to be defined. * * Storing the reader's choice is not a new mechanism: it is a third column * beside the language and locale the preferences service already keeps. * ------------------------------------------------------------------------- */