workbuddy_skills/open-design/design-systems/README.md

Design Systems

Each subfolder is a portable design-system package. Selecting one from the Design System surface or a supported project-creation workflow composes its design context into the agent prompt.

The bundled catalog currently contains 151 packages. Every bundled package has the same minimum machine-readable shape:

design-systems/<slug>/
├── manifest.json
├── DESIGN.md
└── tokens.css

• manifest.json owns stable discovery metadata, provenance, and declared package paths.
• DESIGN.md is the canonical design prose for agents.
• tokens.css is the canonical compiled semantic-token stylesheet.

The daemon still discovers legacy folders that contain only DESIGN.md, so older and user-installed content remains compatible. That fallback is not the authoring target for new repository content.

Manifest and catalog behavior

The v1 manifest uses fixed canonical file names:

{
  "schemaVersion": "od-design-system-project/v1",
  "id": "acme",
  "name": "Acme",
  "category": "Productivity & SaaS",
  "description": "A concise English catalog summary.",
  "source": {
    "type": "bundled",
    "origin": "OpenDesign curated bundled fixture"
  },
  "files": {
    "design": "DESIGN.md",
    "tokens": "tokens.css"
  }
}

• The folder slug and manifest.id must match and use normalized ASCII.
• files.design is DESIGN.md; files.tokens is tokens.css.
• name, category, and description are the primary packaged-catalog copy.
• source records package provenance.
• Every declared path must be safe, relative, and present.

At runtime, manifest metadata takes precedence over the legacy Markdown H1 and > Category: conventions. Those Markdown conventions remain readable fallback metadata for legacy packages. The exact precedence and authoring rules live in docs/design-systems.md.

The catalog is scanned on every /api/design-systems request. After changing a package, refresh the Design System surface; a daemon restart is not required.

Rich package files

Packages may declare the richer files below through their corresponding manifest fields:

USAGE.md                     agent-facing read order and usage guide
components.html              standalone component fixture
components.manifest.json     derived component/token index
design-tokens.json           derived Design Tokens JSON
tailwind-v4.css               derived Tailwind v4 mapping
assets/                       optional static assets
fonts/                        optional webfonts
preview/                      indexed preview pages
source/                       importer evidence, snippets, and token reports

These fields are active runtime inputs, not structural placeholders. Prompt composition consumes USAGE.md, tokens.css, component information, import mode, craft bindings, and a manifest-derived pull index when present. Package and static-file APIs expose declared preview/source files without widening the filesystem boundary.

Derived files are caches rather than competing sources of truth:

• components.manifest.json is derived from components.html and tokens.css.
• design-tokens.json is derived from the token-contract report and must agree with tokens.css.
• tailwind-v4.css is derived from tokens.css.

The manifest and package-quality guards validate the declared paths, rich profile, derived-file parity, token contract, component fixture, source evidence, and preview coverage. Read _schema/AGENTS.md before editing those contracts.

Writing a package

DESIGN.md does not use a fixed nine-section template. The package-quality guard requires at least seven substantive H2 headings for migrated packages, without prescribing their names, order, or numbering. Use headings that fit the actual system and keep their decisions synchronized with tokens.css.

For new repository content:

1. Create the three required files and keep the folder slug equal to manifest.id.
2. Record useful catalog metadata and source provenance in manifest.json.
3. Write at least seven substantive H2 sections in DESIGN.md.
4. Bind the shared semantic-token contract in tokens.css.
5. Add rich package files when the system needs components, previews, assets, fonts, or source evidence.
6. Run pnpm guard and pnpm typecheck.

The complete authoring guide and review checklist are in docs/design-systems.md.

Importing and refreshing

The product exposes local-folder, GitHub, and shadcn import flows in both the UI and the od design-systems import-* CLI. Those importers write the package contract rather than a standalone DESIGN.md.

scripts/sync-design-systems.ts remains the repository-owned bulk synchronizer for upstream-derived catalog content. Do not copy the retired branch-only importer or manual tarball recipe from old plans; use the checked-in script and current import surfaces.

Attribution

Package-level manifest.source, evidence files, and local license files are the source of truth for provenance. Major upstream sources represented in the catalog include:

• VoltAgent/awesome-design-md (MIT) for upstream-derived product systems.
• bergside/awesome-design-skills for normalized design-skill systems.
• tw93/kami (MIT) for the kami package.
• Tom-Opencart/tom-modern-html-style-rule (MIT) for the tom-modern package.

Brand-referencing packages are aesthetic inspirations, not official assets of the brands they reference.