Design system

1.0.16

Tokens, component specs, and a component catalogue for Filip’s products, written in plain CSS and HTML. Any framework can use them.

Choose your path

You are building	Install	Start with
Plain HTMLA static page, a prototype, or an explainer	`@filipgutica/design-system`	`tokens.css`
ReactA React app	`@filipgutica/design-system`	`tokens.css` and `cssVar()`
AgentsClaude or Codex doing UI work for you	`filip-stack host config`	`~/design-system/DESIGN.md`

Plain HTML

Install the package, then import the fonts and tokens before your own styles.

pnpm add @filipgutica/design-system

app.css

@import "@filipgutica/design-system/fonts.css";@import "@filipgutica/design-system/tokens.css";.panel { background: var(--color-surface-raised); border-radius: var(--radius-panel); }

Without a bundler, link fonts/fonts.css and language/tokens.css from the package folder. Pages follow the reader’s system theme; set data-theme="light" or "dark" on <html> to choose one.

Copy component markup and styles from Components.

React

There is no React component library yet. Use the tokens and fonts, and copy each component’s markup and roles from Components.

pnpm add @filipgutica/design-system

main.tsx

import '@filipgutica/design-system/tokens.css'import '@filipgutica/design-system/fonts.css'import { cssVar } from '@filipgutica/design-system'export const Panel = ({ children }: { children: React.ReactNode }) => (  <section style={{    background: cssVar('color-surface-raised'),    padding: cssVar('space-4'),  }}>    {children}  </section>)

cssVar() only accepts names that exist, so a name from before the 2.0.0 token rename, such as text, fails the type check.

Agents

Claude and Codex read the design system from ~/design-system, the package’s language/ folder.

With filip-stack

Install filip-stack, then apply its host config. It installs the design system from a pinned package version and tells Claude and Codex to read it.

filip-stack apply

Without filip-stack

Copy the package’s language/ folder to ~/design-system.

Copy the design system

npm pack @filipgutica/design-system@1.0.16mkdir -p ~/design-system && tar -xzf filipgutica-design-system-1.0.16.tgz -C ~/design-system --strip-components=2 package/language

Then tell your agent to read it. Add this line to CLAUDE.md or AGENTS.md:

CLAUDE.md or AGENTS.md

For UX and visual work, read ~/design-system/DESIGN.md first and follow it.

This site also publishes the files for agents to read:

DESIGN.md: Selection rules and acceptance checks. Agents read it first.
components.md: One spec per component: anatomy, states, Do and Don’t, keyboard, motion, and forced colors.
components.html: Markup and styles to copy, in every state.
llms.txt and index.json: A generated index of every component: its layer, purpose, Do and Don’t lines, and spec.

What the package ships

Every path @filipgutica/design-system 1.0.16 exports.

Import	What it is for
`@filipgutica/design-system`	Typed token data: `tokens` and `cssVar()`
`@filipgutica/design-system/tokens.css`	Every token, light and dark, with the base element styles
`@filipgutica/design-system/themes/*.css`	A theme’s identity inputs, to load after `tokens.css`; the Themes page lists them
`@filipgutica/design-system/themes/*.tokens.json`	Each theme’s source as a W3C Design Tokens file, for design-token tools
`@filipgutica/design-system/tokens.json`	Every value per theme and mode, for tools and generators
`@filipgutica/design-system/theme-mapper`	Experimental. `mapVsCodeTheme()` and `themeVariables()`: a VS Code colour theme as theme inputs, for a theme picker
`@filipgutica/design-system/fonts.css`	IBM Plex Sans and Mono, self-hosted
`@filipgutica/design-system/fonts/*`	The font files
`@filipgutica/design-system/language/*`	The spec, decisions, catalogue, and templates
`@filipgutica/design-system/package.json`	Package metadata

tokens.css also sets base element styles today. A planned release moves them to an opt-in base.css.