Stylos Design System

A design system for dense, desktop-oriented web product interfaces. Its visual language draws on antiquity, classical architecture and constructed proportion — strict and structural rather than decorative.

0.2.0 ships the current starting set for early product integration. The core set has a Svelte 5 implementation, independent CSS and a generated workshop. The urgent additions retain draft contracts. All unfinished acceptance moves to 0.3.0; product proof and consumer materials move to 0.4.0. The package stays private. This owner-directed release does not establish full accessibility or Figma parity; see PLAN.md §1.

Owner	Artur Trifonov
Figma	Styles · Components · GUI components · Playground — keys in figma/README.md
Icons	Current default preset: Material Symbols Rounded; Figma still uses the external Default Kit / Material Icons until it is aligned
Repository	https://github.com/arturtrifonov/stylos
Design tool	Figma
Platform	web, desktop-oriented applications
Implementation	Svelte 5
License	undecided; unlicensed for external use until chosen

Start here

docs/charter.md	what the system is for, its character, and where its boundaries are
ARCHITECTURE.md	how it is put together — what lives where, and what is currently broken
docs/foundations/	the rules of the design language
PLAN.md	the release ladder, and the stages that reach each tag

What is here

docs/          charter, principles, the rules of rules, foundations, component standard and registry
tokens/        the canonical token set, imported from Figma
packages/ui/   @stylos/ui — the Svelte 5 component package, built from the registry's contracts
apps/workshop/ the Storybook workshop for @stylos/ui; stories are generated, run locally
skills/        Figma Agent skills — modular source, compiled to one importable document
tools/         small dependency-free scripts that build and check the above
assets/        the wordmark and the two self-hosted families, for the generated site
figma/         what the Figma library contains; Figma itself stays the source of truth

Each directory has a README.md explaining what belongs in it.

Figma and this repository

Figma holds the values — variables and styles — and tokens/ imports them. It does not hold component contracts: those are authored here, and Figma is one implementation of them, checked against them (ARCHITECTURE.md §1).

The repository never writes to Figma — an explicit non-goal until a reliable round trip exists (ARCHITECTURE.md §1).

Variables move one way. An export is made by hand and read once:

npm run tokens:import -- ~/Downloads   # export → tokens/
npm run tokens:check                   # verify the record against itself
npm run tokens:report                  # render current values

The exported files are not kept — tokens/*.yaml is the record, and its history is in git.

Working on it

Once per clone:

git config core.hooksPath .githooks

A hooks path is not configured by cloning, and the hooks are the guard that binds a hand as well as an agent: no commit on master, no push to it outside the release ritual (ARCHITECTURE.md §7). Work branches from master and arrives by pull request.

npm install
npm test                  # tool tests
npm run build:skills      # skills/src/ → skills/dist/, imported into Figma Agent by hand
npm run validate:registry # component registry: contradictions fail, judgements are reported
npm run build             # → build/, the whole publishable site
npm run dev               # local site at http://127.0.0.1:4173/, rebuilds and reloads on edits
npm run build:publish     # the same, plus the Storybook workshop at build/storybook/
npm run registry:view     # → build/registry.html alone, while editing YAML
npm run components:view   # → build/components/ alone, one page per component

npm run build produces something uploadable: it writes the front page, the registry view and every component page, and copies assets/ in beside them. npm run build:publish is the tree the site is published from — it builds the workshop first and copies it in (SPEC 0011); the deploy itself is a manual upload. The last two are the same renderers on their own, for the loop where a rebuild of 101 pages is not worth waiting for — they do not copy the fonts, so a page built that way falls back to the system stack.