Website design system
Owns the how it looks and performs visually layer: mobile graphics, dark
mode, and the theme tokens. Outputs/maintains BRAND.md (template: the new-website
skill's templates/brand.md) and the token block in that skill's
templates/astro/src/styles/global.css. Image rules
are below (WebP/AVIF via Astro's astro:assets); the images.spec.ts test
enforces them. For generating image assets, use the image skill.
Dark mode (first-class)
- Tokens, not hard-coded colours. All colour flows through CSS custom
properties; light is the
:root default, dark overrides under
:root[data-theme="dark"], plus a @media (prefers-color-scheme: dark) block
for no-JS visitors. The starter ships this exact structure.
- No-FOUC script in
<head> sets data-theme from localStorage.theme or
the system preference before first paint (already wired in Base.astro).
The toggle writes localStorage.theme (the starter ships none; if you add one,
say so in the privacy page's section 3).
- Contrast both themes: every text/background pair passes WCAG AA (4.5:1
body, 3:1 large/UI). A colour that passes in light often fails in dark — the
a11y test runs the full light+dark matrix, so check both.
Mobile & responsive graphics
- Mobile first: design from 360px up; tap targets ≥ 44px; no horizontal
scroll. Verify at 360 / 768 / 1280 (preview_resize).
- Modern formats: WebP (or AVIF) over JPEG/PNG for photos.
- Size to display, not source. Never ship a 2000px image into an 80px slot;
generate width variants and use
srcset/sizes (or <picture>).
- No layout shift: set explicit
width/height attributes so the box is
reserved before the image loads (protects CLS / LCP). Astro's <Image> sets them
automatically; images.spec.ts requires the attributes (a CSS-only aspect-ratio
will not satisfy the test).
- Lazy vs eager:
loading="lazy" below the fold; the LCP/hero image loads
eager with fetchpriority="high" (do NOT lazy-load it).
- Alt text on every image (
alt="" only if purely decorative).
- Fonts: self-host woff2 with
font-display: swap; preload only the 1–2 used
above the fold. Avoid layout shift from late font swaps.
Text-length responsiveness (translated copy)
- Translated text runs longer. German (and many other languages) commonly runs
20–35% longer than the equivalent English copy. A button, nav link, or card sized
to fit English placeholder text will silently overflow, wrap ugly, or truncate the
moment real translated copy replaces it.
- Prefer flexible widths. Use
min-width / flex / grid auto/fr sizing for any
element holding translated text, not a fixed width sized to the English string.
- Overflow ≠ width: flexible sizing doesn't stop a SINGLE long compound noun
(
Datenschutzerklärung) from bursting a narrow column — that needs
hyphens: auto (correct per-language via the lang attribute Base.astro already
sets) plus overflow-wrap: break-word as the fallback; the starter's global.css
ships both on body. Table cells turn hyphenation off (see Tables).
- Don't rely on
white-space: nowrap + text-overflow: ellipsis alone as the
handling for nav links or button labels — truncating a nav link is usually not
acceptable UX (the visitor can no longer tell where it goes). Fine for content
where truncation is an accepted tradeoff (e.g. a table cell), not for navigation.
- Verify with real translated labels, not English placeholders. When a site ships
astro-i18n-setup's LanguageSwitcher.astro or any bilingual/multilingual nav,
check layout at 360/768/1280 (preview_resize) using the actual shipped copy in
every language — not just the English placeholder.
Tables
One style for every table; a page carries no layout CSS for a table. It lives in the starter's
src/styles/tables.css (imported after global.css by Base.astro) and tests/tables.spec.ts checks
it. A site made before this section copies tables.css in, adds the import line to its layout, and
removes each page's own table CSS first.
Two kinds, told apart by what the cells hold:
stack (sentences): a table above 40rem; below it each row stacks, the row header as a title and
each cell under its column's name. Four columns of prose cannot share 320px.
figures (short numbers, class="num" on a number cell): stays a table on a phone and must fit in
320px. If it no longer fits, make it stack; a scroll bar is not the fix. stack figures together is
the figures look with the stacked layout.
Markup, every table:
<div class="table-wrap stack" role="region" aria-label="What the table shows" tabindex="0">
<table role="table">
<thead role="rowgroup"><tr role="row">
<th scope="col" role="columnheader">{cols[0]}</th><th scope="col" role="columnheader">{cols[1]}</th>
</tr></thead>
<tbody role="rowgroup">{rows.map((r) => (
<tr role="row"><th scope="row" role="rowheader">{r.item}</th><td role="cell" data-label={cols[1]}>{r.text}</td></tr>
))}</tbody>
</table>
</div>
- Write the column names once, in a list, and use it for the header and for every
data-label: the label
of a stacked cell must equal its column header, and the test compares the two. A figures table needs no
per-cell roles and no data-label.
- A stacked table is no longer
display: table. The roles are a fallback for a browser that drops the
table when the layout changes; that they work there is not checked. In Chromium, measured once on a real
table, the accessibility tree kept the table without them.
class="tap" on a link that stands alone in a cell makes it a 44px tap target on a phone. nowrap keeps a
short value (1, 3, 6) on one line. long-head (with stack) widens the first column when the row
headers are sentences.
- Words are not hyphenated in cells. The body's
hyphens: auto squeezes a narrow first column to
fragments ("An-thropic"), so the block sets hyphens: manual there.
- A page whose tables come from outside and cannot carry the markup goes into
TABLE_EXEMPT in the spec,
with the reason. PAGES stays whole: the sitemap and llms.txt checks need every live route in it.
What tables.spec.ts checks: every table is in a .table-wrap of one kind with its region, label and
tabindex, scope="col" on every header cell and a <th scope="row"> as the first cell of every row, with <td> for the rest; a stacked table has its roles and a label equal to the header on each cell; at 360 and 320px no
page and no table scrolls sideways; at 641px and above a stacked table is a table again with its header row
showing and no word broken (this catches rules such as overflow-wrap: anywhere that let a column squeeze a
word); no cell has hyphens: auto. It also tests the CSS on a fixture it adds to the
home page, with axe in both themes, so a site with no table still proves the block. Headless Chromium does
not hyphenate, so the hyphen guard reads the computed style, not the layout. Safari and VoiceOver are not
checked.
Email obfuscation (hide addresses from crawlers)
Never put a plaintext email or mailto:your@addr in the HTML source — scrapers harvest it
for spam within hours. Render every address through the EmailLink.astro component
(src/components/EmailLink.astro in the new-website skill's templates/astro/, + its
lib/obfuscate.ts helper): the address is reversed + base64-encoded at build time and
reassembled in the browser, so the served HTML contains no readable address. No-JS visitors
see a still-usable "name [at] domain [dot] com" hint.
<EmailLink address="hello@example.com" subject="Project enquiry" text="Email us" />
Rule: zero raw mailto: links and zero literal @-addresses in built HTML — website-qa
checks this. Same idea for any phone number you don't want harvested.
Brand tokens
Mirror BRAND.md's palette into the token block and keep them in sync. Define:
brand (fixed), and per-theme heading/ink/muted/accent/link/line/bg/bg-soft/surface. The
accent and the link colour must pass AA on the background in both themes, which is why
each theme has its own. The optional website-brand-kit does the mirroring with a
check: its intake reads BRAND.md's tables, holds every text colour to 4.5:1 on every
background in both themes, and writes the values into all three colour blocks of
global.css (light, dark, and the dark block for visitors without JavaScript). By hand,
change all three blocks together.
Done means
BRAND.md filled and consistent with the token block; images are WebP, sized,
lazy/eager-correct, with alt; the a11y test (light+dark) is green; layout holds
at 360/768/1280 with no shift; every table is stack or figures and tables.spec.ts is green. Perf numbers (FCP/LCP) are verified in website-qa.
Layout also holds at 360/768/1280 with real (not placeholder) copy in every
shipped language, not just the default locale.
1---2name: website-design-system3description: >4 The visual build standards for a new site: mobile-first responsive graphics5 (WebP/AVIF, sized-to-display, srcset, lazy-load, descriptive alt, no layout6 shift), dark mode (CSS-variable theme tokens + a no-FOUC script + WCAG AA7 contrast in BOTH themes), and the brand/theme token block that BRAND.md8 mirrors. Use when building or reviewing layout, images, theming, or BRAND.md9 (step 6 of the new-website pipeline). Contrast is enforced by a11y.spec.ts10 (light+dark). Trigger phrases: "dark mode", "theme toggle", "responsive11 images", "mobile optimization", "image optimization", "WebP", "layout shift",12 "CLS", "design system", "theme tokens", "brand colors", "BRAND.md".13metadata:14 source: https://skillmd.com/skills/karero/website-design-system15---1617# Website design system1819Owns the **how it looks and performs visually** layer: mobile graphics, dark20mode, and the theme tokens. Outputs/maintains `BRAND.md` (template: the `new-website`21skill's `templates/brand.md`) and the token block in that skill's22`templates/astro/src/styles/global.css`. Image rules23are below (WebP/AVIF via Astro's `astro:assets`); the `images.spec.ts` test24enforces them. For generating image assets, use the `image` skill.2526## Dark mode (first-class)2728- **Tokens, not hard-coded colours.** All colour flows through CSS custom29 properties; light is the `:root` default, dark overrides under30 `:root[data-theme="dark"]`, plus a `@media (prefers-color-scheme: dark)` block31 for no-JS visitors. The starter ships this exact structure.32- **No-FOUC script** in `<head>` sets `data-theme` from `localStorage.theme` or33 the system preference *before first paint* (already wired in `Base.astro`).34 The toggle writes `localStorage.theme` (the starter ships none; if you add one,35 say so in the privacy page's section 3).36- **Contrast both themes:** every text/background pair passes WCAG AA (4.5:137 body, 3:1 large/UI). A colour that passes in light often fails in dark — the38 a11y test runs the full light+dark matrix, so check both.3940## Mobile & responsive graphics4142- **Mobile first:** design from 360px up; tap targets ≥ 44px; no horizontal43 scroll. Verify at 360 / 768 / 1280 (preview_resize).44- **Modern formats:** WebP (or AVIF) over JPEG/PNG for photos.45- **Size to display, not source.** Never ship a 2000px image into an 80px slot;46 generate width variants and use `srcset`/`sizes` (or `<picture>`).47- **No layout shift:** set explicit `width`/`height` **attributes** so the box is48 reserved before the image loads (protects CLS / LCP). Astro's `<Image>` sets them49 automatically; `images.spec.ts` requires the attributes (a CSS-only aspect-ratio50 will not satisfy the test).51- **Lazy vs eager:** `loading="lazy"` below the fold; the LCP/hero image loads52 eager with `fetchpriority="high"` (do NOT lazy-load it).53- **Alt text on every image** (`alt=""` only if purely decorative).54- **Fonts:** self-host woff2 with `font-display: swap`; preload only the 1–2 used55 above the fold. Avoid layout shift from late font swaps.5657### Text-length responsiveness (translated copy)5859- **Translated text runs longer.** German (and many other languages) commonly runs60 20–35% longer than the equivalent English copy. A button, nav link, or card sized61 to fit English placeholder text will silently overflow, wrap ugly, or truncate the62 moment real translated copy replaces it.63- **Prefer flexible widths.** Use `min-width` / flex / grid `auto`/`fr` sizing for any64 element holding translated text, not a fixed `width` sized to the English string.65- **Overflow ≠ width:** flexible sizing doesn't stop a SINGLE long compound noun66 (`Datenschutzerklärung`) from bursting a narrow column — that needs67 `hyphens: auto` (correct per-language via the `lang` attribute Base.astro already68 sets) plus `overflow-wrap: break-word` as the fallback; the starter's `global.css`69 ships both on `body`. Table cells turn hyphenation off (see Tables).70- **Don't rely on `white-space: nowrap` + `text-overflow: ellipsis` alone** as the71 handling for nav links or button labels — truncating a nav link is usually not72 acceptable UX (the visitor can no longer tell where it goes). Fine for content73 where truncation is an accepted tradeoff (e.g. a table cell), not for navigation.74- **Verify with real translated labels, not English placeholders.** When a site ships75 `astro-i18n-setup`'s `LanguageSwitcher.astro` or any bilingual/multilingual nav,76 check layout at 360/768/1280 (preview_resize) using the actual shipped copy in77 every language — not just the English placeholder.7879## Tables8081One style for every table; a page carries no layout CSS for a table. It lives in the starter's82`src/styles/tables.css` (imported after `global.css` by `Base.astro`) and `tests/tables.spec.ts` checks83it. A site made before this section copies `tables.css` in, adds the import line to its layout, and84removes each page's own table CSS first.8586Two kinds, told apart by what the cells hold:8788- **`stack`** (sentences): a table above 40rem; below it each row stacks, the row header as a title and89 each cell under its column's name. Four columns of prose cannot share 320px.90- **`figures`** (short numbers, `class="num"` on a number cell): stays a table on a phone and must fit in91 320px. If it no longer fits, make it `stack`; a scroll bar is not the fix. `stack figures` together is92 the figures look with the stacked layout.9394Markup, every table:9596```astro97<div class="table-wrap stack" role="region" aria-label="What the table shows" tabindex="0">98 <table role="table">99 <thead role="rowgroup"><tr role="row">100 <th scope="col" role="columnheader">{cols[0]}</th><th scope="col" role="columnheader">{cols[1]}</th>101 </tr></thead>102 <tbody role="rowgroup">{rows.map((r) => (103 <tr role="row"><th scope="row" role="rowheader">{r.item}</th><td role="cell" data-label={cols[1]}>{r.text}</td></tr>104 ))}</tbody>105 </table>106</div>107```108109- Write the column names once, in a list, and use it for the header and for every `data-label`: the label110 of a stacked cell must equal its column header, and the test compares the two. A `figures` table needs no111 per-cell roles and no `data-label`.112- A stacked table is no longer `display: table`. The roles are a fallback for a browser that drops the113 table when the layout changes; that they work there is not checked. In Chromium, measured once on a real114 table, the accessibility tree kept the table without them.115- `class="tap"` on a link that stands alone in a cell makes it a 44px tap target on a phone. `nowrap` keeps a116 short value (`1, 3, 6`) on one line. `long-head` (with `stack`) widens the first column when the row117 headers are sentences.118- Words are not hyphenated in cells. The body's `hyphens: auto` squeezes a narrow first column to119 fragments ("An-thropic"), so the block sets `hyphens: manual` there.120- A page whose tables come from outside and cannot carry the markup goes into `TABLE_EXEMPT` in the spec,121 with the reason. `PAGES` stays whole: the sitemap and `llms.txt` checks need every live route in it.122123What `tables.spec.ts` checks: every table is in a `.table-wrap` of one kind with its region, label and124`tabindex`, `scope="col"` on every header cell and a `<th scope="row">` as the first cell of every row, with `<td>` for the rest; a stacked table has its roles and a label equal to the header on each cell; at 360 and 320px no125page and no table scrolls sideways; at 641px and above a stacked table is a table again with its header row126showing and no word broken (this catches rules such as `overflow-wrap: anywhere` that let a column squeeze a127word); no cell has `hyphens: auto`. It also tests the CSS on a fixture it adds to the128home page, with axe in both themes, so a site with no table still proves the block. Headless Chromium does129not hyphenate, so the hyphen guard reads the computed style, not the layout. Safari and VoiceOver are not130checked.131132## Email obfuscation (hide addresses from crawlers)133134Never put a plaintext email or `mailto:your@addr` in the HTML source — scrapers harvest it135for spam within hours. Render every address through the **`EmailLink.astro`** component136(`src/components/EmailLink.astro` in the `new-website` skill's `templates/astro/`, + its137`lib/obfuscate.ts` helper): the address is reversed + base64-encoded at build time and138reassembled in the browser, so the served HTML contains no readable address. No-JS visitors139see a still-usable "name [at] domain [dot] com" hint.140141```astro142<EmailLink address="hello@example.com" subject="Project enquiry" text="Email us" />143```144Rule: **zero raw `mailto:` links and zero literal `@`-addresses in built HTML** — `website-qa`145checks this. Same idea for any phone number you don't want harvested.146147## Brand tokens148149Mirror `BRAND.md`'s palette into the token block and keep them in sync. Define:150brand (fixed), and per-theme heading/ink/muted/accent/link/line/bg/bg-soft/surface. The151accent and the link colour must pass AA on the background in both themes, which is why152each theme has its own. The optional `website-brand-kit` does the mirroring with a153check: its intake reads `BRAND.md`'s tables, holds every text colour to 4.5:1 on every154background in both themes, and writes the values into all three colour blocks of155`global.css` (light, dark, and the dark block for visitors without JavaScript). By hand,156change all three blocks together.157158## Done means159160`BRAND.md` filled and consistent with the token block; images are WebP, sized,161lazy/eager-correct, with alt; the a11y test (light+dark) is green; layout holds162at 360/768/1280 with no shift; every table is `stack` or `figures` and `tables.spec.ts` is green. Perf numbers (FCP/LCP) are verified in `website-qa`.163Layout also holds at 360/768/1280 with **real** (not placeholder) copy in every164shipped language, not just the default locale.