Overview

A system-wide reference for tokens, components, and the rules that tie Dino together.

Principles

Four beliefs that drive every decision in the system: from token naming to shadow depth.

01

Details matter

Shadows, pressed states, gradient fills: each one imperceptible on its own. Together they make the product feel crafted, not assembled.

02

Feedback is constant

Every action gets a visual reaction. Hover, pressed, disabled, error, success: all distinct. In a learning app, clarity keeps the flow.

03

One source of truth

No hardcoded values, ever. Every color, size, and shadow flows from tokens. Change the token, change everything at once.

04

Dark by default

Reduces eye strain in late-night study sessions and gives the app the visual energy of a game, not a textbook.

Architecture

Tokens follow three layers of abstraction. Each layer has one job. Components only ever consume the third.

Brand
Primitives

Raw values with no context. #4ed21e, 16px, Rubik. They exist only to be referenced, never used directly in components.

--green-default --grey-800 --scale-400
Semantic
Roles

Names with intent. Primary, Error, Spacing. They say what a value is for, not what it looks like.

--primary-600 --error-default --spacing-16
Component
Context

What components consume. Named by surface and state. Dark mode is the default; light is a theme override.

--surface-button-primary-default --text-headings --border-action-default

Built for agents

This design system is built to be read by humans and understood by agents. Every component ships with a doc page for the team and a .meta.js for AI tools (same decisions, structured two ways so anyone or anything working in this repo starts with the full picture).

How it works

Each component ships with a .meta.js file that encodes what the doc page communicates in prose: variants, consumed tokens, composition rules, accessibility requirements, and anti-patterns. An agent that reads that file knows as much about the component as a designer who built it.

Repo structure

Every component lives in three layers: the implementation, the documentation, and the metadata. Each file has one job.

[Name].astro src/components/[name]/

The real component. Props, markup, and styles. No documentation content.

[name].meta.js src/components/[name]/

Structured metadata for agents. Variants, consumed tokens, relationships, accessibility, and anti-patterns. The machine-readable version of the doc page.

[name].astro src/pages/components/

The public documentation page. Playground, variants, usage, combinations, and do's & don'ts.

components.index.meta.js src/data/

Master index of all components. The entry point for any agent exploring the system.

global.css public/styles/

Source of truth for all CSS tokens. Three layers: Brand, Semantic, Components/Dark. Every Component-layer token has a comment explaining when to use it.

COMPONENT-METADATA-SCHEMA.md root

Reference schema for creating new components. Defines what fields each .meta.js must have and why.

CLAUDE.md root

Instructions for Claude Code. Project rules, naming conventions, and the process for adding new components.

This structure means a new component is ready for human use and AI use at the same time. Design it, build it, document it, encode it.