# Design System

This is the canonical entry point for the YotoShelf design system. The system is defined in this repository, [gitlab.com/yotoshelf/yotoshelf.dev](https://gitlab.com/yotoshelf/yotoshelf.dev), and consumed by the application as the `frontend/design` submodule. If a colour, a type step, or a component variant is not in the files below, it is not part of the system.

## Where the system lives

| Path | What it defines |
|---|---|
| `packages/tokens/tokens.css` | Every colour, type, spacing, radius, and shadow token. The source of truth for values — the pages under [Design System](/design) describe what is in this file, they do not add to it. |
| `packages/tokens/tailwind-theme.css` | The same tokens exposed as a Tailwind v4 theme block, for consumers building with Tailwind. |
| `packages/components/` | Shared Svelte 5 components: Button, Card, Badge, Input, Dialog, Callout, Carousel, TocRibbon, and the specimen components the design pages render. |
| `src/styles/global.css` | Token import plus base element styling for this site. |
| `public/logo/` | The pixel-art mark, the hero banner, and the favicons. |

## The reference pages

The [Design System](/design) section documents the files above, one concern per page:

- [Overview](/design) — design direction, brand identity, and the principles the rest of the section applies
- [Colors](/design/colors) — the accent in two weights, the computed contrast table, neutrals, and semantic colours
- [Typography](/design/typography) — the two faces, the measured type scale, weights, and line heights
- [Spacing](/design/spacing) — the 4px-base scale, the radius split, and the shadow scale
- [Components](/design/components) — live demos of every shared component and its variants
- [Logo](/design/logo) — mark, hero banner, favicons, and usage rules
- [Process](/design/process) — how the mark was made and how to iterate it
- [Integration](/design/integration) — consuming the tokens and components in your own project

## Consuming it

The application pins this repository as a git submodule at `frontend/design` and imports tokens and components from it. There is no package publish and no semantic version: a commit on `main` is the release, and a consumer moves by advancing the submodule pointer. [Integration](/design/integration) carries the commands.

## Changing it

A token value changes in `packages/tokens/tokens.css` and nowhere else, and the page that documents it changes in the same commit. A new component lands in `packages/components/` with a demo on the [Components](/design/components) page. The contrast ratios on the [Colors](/design/colors) page are computed from the token hexes rather than eyeballed, so a colour change means re-deriving them.