# [Your name or project] · Design system Blank kit from fabiostaiano.it/en/design-system/. The base rules are already written and work for any brand; the places marked **[TO CHOOSE]** are yours. The values live in `tokens.css` and `tokens.json`: neutral colours and a placeholder accent that work straight away, in light and dark. **How to fill it in with an AI assistant.** Give this file and the two token files to Claude or ChatGPT, together with your website or a few screenshots, and write: *"Fill in every [TO CHOOSE] in this design system by looking at my site. Don't change the base rules. Update tokens.css and tokens.json with the same values."* Then read it back: the assistant suggests, you decide. ## The rules that don't break Rules 1, 2, 3, 5 and 6 of this kit are rules 2, 4, 6, 7 and 8 of the fabiostaiano.it design system, without the brand. Rules 4, 7 and 8 of this kit are about method: how you work, not how it looks. 1. **One accent per composition.** The accent colour goes to one thing per screen, the one that matters. Everything else stays in the neutrals. 2. **The biggest is the most contrasted.** What matters most is bigger and higher in contrast. Never two different things with the same weight. 3. **Accessible by rule.** Text contrast at least 4.5:1, 3:1 for large headings and for borders you need to understand the page. Touch areas of 44×44 px. With "reduce motion" on, animations stop. Colour never carries meaning on its own. 4. **Focus is visible.** Every element you can reach with the keyboard has a visible outline. Never `outline:none` without a replacement. 5. **Text centred on the real glyphs.** When a heading sits in a tile or on an axis, it is centred on the drawing of the letters, not on the font's box. 6. **Light and vector first.** Logo, icons and illustrations in SVG; raster images only for photos, in WebP or AVIF at the size they are shown. Fonts in WOFF2, only the weights and characters you need. A page's weight is measured before it goes live. 7. **Light and dark from the same tokens.** Pages use the names (`--paper`, `--ink`), never hand-written colours. A theme changes the values, not the pages. 8. **A value used twice becomes a token.** If a colour, a size, a shadow or a layer is needed twice, it gets a name in `tokens.css`. ## Foundations ### Colour - **Neutrals.** Ready in `tokens.css`, light and dark: `--paper` (background), `--wash` (surfaces), `--line` (borders), `--muted` (secondary text), `--ink` (main text). You can warm them up or cool them down: keep the contrast of rule 3. - **Accent.** `--accent` is a placeholder. **[TO CHOOSE: your main colour, in hex, and its version for dark]**. Check that `--on-accent` (text on the accent) reaches 4.5:1. - **Supporting colours.** **[TO CHOOSE: three at most, only for illustrations and charts, never for small text. If you don't need them, write "none"]**. - **Errors and confirmations.** A sentence that says what to do, as well as the colour. **[TO CHOOSE: if you use a red for errors, its value]**. ### Typography - **Headings:** **[TO CHOOSE: typeface, weights]**. In the kit: system fonts. - **Body:** **[TO CHOOSE: typeface, regular and bold weight]**. Body 16 px, line height 1.5, lines of 64 characters at most. - **Labels and numbers:** **[TO CHOOSE: typeface, usually a monospace or spaced capitals]**. - **Scale:** **[TO CHOOSE: 5-6 sizes, from the biggest heading to the note]**. A new size is added here before it's used. ### Grid and spacing - **Container:** `--max` (1120 px in the kit) with `--gutter` on the sides. Content and footer start from the same edge. - **Spacing:** multiples of 4 px (`--s-1` … `--s-8`). No values by eye. - **Breakpoints:** **[TO CHOOSE: usually 560, 760, 1100 px]**. ### Shape and depth - **Corners:** **[TO CHOOSE: square (0) or rounded (e.g. 8 px)]**. One choice for the interface; pills (tags, chips) can be round. - **Shadows:** **[TO CHOOSE: none, soft or hard]**. Two at most: one for raised surfaces, one for dialogs. ### Motion - Short timings: 0.2 s for colours and borders, 0.35 s for fades, 0.5 s for movement. - An animation follows a gesture (hover, click, appearing), it doesn't decorate. Rule 3 always applies. ### Icons - **[TO CHOOSE: icon set or hand-drawn; outline or filled; size (e.g. 20 px)]**. An icon on its own always has an accessible name. ## Brand ### Logo - **[TO CHOOSE: versions (on light, on dark), minimum size, clear space]**. ### Illustrations - **[TO CHOOSE: style in one sentence, allowed palette, what is never drawn]**. Rule 1 applies here too: one coloured lead. ### Tone of voice - **[TO CHOOSE: three adjectives, and one example of a right sentence and a wrong one]**. - Always true: short sentences; the button says what happens, with a verb (*Subscribe*, never *Submit* or *Click here*); errors say what to do; no jargon where a normal word will do. ## Interface ### Components - **Primary button:** `--ink` (or `--accent`) background, `--paper` text, at least 44 px tall. - **Secondary button:** border in `--line` that turns `--ink` on hover. - **Field:** visible border, at least 44 px tall, always with a label (a placeholder isn't enough). The error is a sentence under the field. - **Link:** underlined, in `--link`. - **Dialog:** closes with Esc and with a 44×44 px button; focus moves into the dialog and then back to where it was. - **Tag:** small pill, `--line` border, `--muted` text. - **[TO CHOOSE: the other components of your project, one per line, with where they live]**. ### States and interaction - **Focus:** 2 px `--link` outline, 2 px offset, the same on every element. - **Hover:** solid button at 0.86 opacity; secondary button with the border in `--ink`; link with a heavier underline. - **Disabled:** 0.5 opacity and a sentence that says why. Never colour alone. ### Pages - Values come from `tokens.css`, once. Pages don't write new colours, fonts or shadows. - **Inventory:** a component lives in one place only. **[TO CHOOSE: list your components here and the file they live in]**. ## Channels - **[TO CHOOSE: social, email, slides. For each: format, background, what stays the same as the site]**. ## Files - `DESIGN.md`: these rules, with the reasons. - `tokens.css` and `tokens.json`: the same values, for code and for design tools. - **Licence:** CC BY 4.0. Use it and change it as you like, at work and for clients too, crediting fabiostaiano.it/en/design-system/.