Design system

The framework-agnostic foundation for every interface Filip builds. Its tokens, components, and rules are plain HTML and CSS: the UI library implements them in Vue, new apps and libraries start from them, and Claude and Codex follow them for visual work.

This design system is published as filipgutica/design-system. It is the default for UX and visual work, unless you ask for another or the repository has its own. Browse it on the design system site.

Installed to: ~/design-system
Installed by: filip-stack apply
Source: @filipgutica/design-system
Theme: Graphite Indigo

Component catalogue

The catalogue shows every component in each state that applies. It uses only tokens.css, and its markup carries the roles and states each implementation copies. @filipgutica/ui builds these components in Vue; a React library or a new app builds the same ones from here.

Component catalogue: each component and its states.
Foundations: type, color, spacing, shape, borders, elevation, focus, and motion.
Examples: application, documentation, and product page.
Component specs and decisions: what each component does, and why it looks the way it does.

How agents use it

The shared guidance tells agents to read ~/design-system/DESIGN.md before UX or visual work. For interaction, flows, states, interface copy, and accessibility, they also use the interface-design skill. DESIGN.md owns the look; interface-design owns the behavior and its checks.

Your request wins over everything else.
A repository's own design system owns its tokens and components.
filipgutica/design-system is the default for all other UX and visual work. Use its palette, type, and components consistently across projects.

Pick the format first

Choose the format before styling. It determines the density and what the reader sees first.

Format	Lead with
`Product page`	Purpose, one primary action, and a real product image.
`Docs or CLI tool`	The setup command or the information the task needs.
`Application`	Working content and its actions.
`Inline visual`	The comparison or explanation itself, in the host's theme.

Reuse it in a new project

The design system has two layers. The core covers tokens, quiet depth, controls and their states, focus, motion, and accessibility, and a new project adopts it as is. The identity layer is the personal sites' terminal look: the ~/name header, mono headings, and command plates. A new project replaces it with its own.

To start, keep tokens.css unchanged and set your own hue and fonts on :root in a stylesheet loaded after it. Then build components from the catalogue and the component specs.

Theme and token names

Graphite surfaces separate regions. Indigo marks primary actions; blue marks links. Focus is one indigo ring with a 3px gap. Switch the appearance in the header to compare light and dark.

--color-bgPage

--color-surfaceRegions

--color-surface-raisedControls

--color-textBody text

--color-mutedSecondary

--color-accentPrimary action

--color-linkLinks

--color-successState

--color-warningState

--color-errorState

The labels above are token names. Standalone HTML and library sites use the same names. The values come from @filipgutica/design-system, which generates tokens.css and the @filipgutica/ui theme. See the components in the UI library.

Rules and examples in the folder

File	Use it for
`DESIGN.md`	Rules for choosing a format, styling the work, and checking the result.
`tokens.css`	Theme values to import or inline in standalone HTML. The project hue and fonts sit in one block at the top.
`components.md`	One spec for each component, marked core or identity.
`components.html`	Every component in each of its states, in plain HTML and CSS.
`decisions.md`	Why each component looks the way it does, and the options it replaced.
`docs.html`	Example documentation shell with a compact setup command.
`product.html`	Example product page hierarchy.
`reference.html`	Example application, and a catalogue of type, color, spacing, shape, borders, elevation, focus, and motion.

Where to make changes

Edit the rules, examples, and tokens in filipgutica/design-system, which publishes them as @filipgutica/design-system. filip-stack pins one published version in host-config/design-system.json. After a release, bump the pin with node scripts/pin-design-system.mjs <version>, merge it, then run filip-stack update on each machine.