website-design-system
/website-design-system
Ustala standardy wizualne nowej strony: responsywne grafiki WebP/AVIF, tryb ciemny, tokeny motywu i kontrast WCAG AA.
- Autor
- karero ↗
- Repozytorium
- croftweaver ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Ustala standardy wizualne nowej strony: responsywne grafiki WebP/AVIF, tryb ciemny, tokeny motywu i kontrast WCAG AA.
Wyzwalacze z opisu
Oryginalny opis (EN)
The visual build standards for a new site: mobile-first responsive graphics (WebP/AVIF, sized-to-display, srcset, lazy-load, descriptive alt, no layout shift), dark mode (CSS-variable theme tokens + a no-FOUC script + WCAG AA contrast in BOTH themes), and the brand/theme token block that BRAND.md mirrors. Use when building or reviewing layout, images, theming, or BRAND.md (step 6 of the new-website pipeline). Contrast is enforced by a11y.spec.ts (light+dark). Trigger phrases: "dark mode", "theme toggle", "responsive images", "mobile optimization", "image optimization", "WebP", "layout shift",
Jak działa
- Dark mode (first-class)
- Mobile & responsive graphics
- Tables
- Email obfuscation (hide addresses from crawlers)
- Brand tokens
- Done means
Podgląd SKILL.md
---
name: website-design-system
description: >
The visual build standards for a new site: mobile-first responsive graphics
(WebP/AVIF, sized-to-display, srcset, lazy-load, descriptive alt, no layout
shift), dark mode (CSS-variable theme tokens + a no-FOUC script + WCAG AA
contrast in BOTH themes), and the brand/theme token block that BRAND.md
mirrors. Use when building or reviewing layout, images, theming, or BRAND.md
(step 6 of the new-website pipeline). Contrast is enforced by a11y.spec.ts
(light+dark). Trigger phrases: "dark mode", "theme toggle", "responsive
images", "mobile optimization", "image optimization", "WebP", "layout shift",
"CLS", "design system", "theme tokens", "brand colors", "BRAND.md".
---
# 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:
```astro
<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.
```astro
<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.
Wersje
W bazie nie ma innych skilli o nazwie website-design-system.
Migawka bazy z 13.11.2026 · wersja paczki 498ccd85a95e (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 95frontend-theming
Wdraża tryb ciemny i jasny oraz system motywów na zmiennych CSS, tokenach projektowych i przełączniku motywu. - 100design-system
Kompiluje tokeny designu, motywy jasny i ciemny oraz walidację kontrastu WCAG dla dokumentów i decków HTML w jeden wstrzykiwalny pakiet CSS. - 90frontend-image-optimization
Optymalizuje obrazy na stronie: formaty WebP i AVIF, responsywne srcset, leniwe ładowanie, zastępcze podglądy i integrację z CDN. - 90theming-system
Projektuje architekturę motywów: warianty marki, tryb ciemny i wysoki kontrast, mapowane przez warstwy tokenów, gdy jeden system obsługuje wiele motywów. - 100theming
Pomaga budować system motywów interfejsu: architektura tokenów, tryb ciemny, zachowanie kontrastu między motywami i generowanie spójnej palety z jednego koloru. - 100taste-tokens
Buduje system tokenów projektowych: warstwy prymitywów, semantyki i komponentów, motywy jasny, ciemny i wysokiego kontrastu oraz pliki CSS i Tailwind.