@bossjob-ds/ds

The agent-consumption layer of the Bossjob Design System. One command wires an app repo's AI coding agents (Claude Code / Cursor / any AGENTS.md-aware tool) to the DS so they reuse @bossjob-ds/* + tokens instead of re-drawing <div>s with hardcoded colors.

npx @bossjob-ds/ds init

Why this exists

The north star is: design → code and requirements → prototype, both kept consistent with production by one source of truth. The missing link on our Figma tier is Code Connect (Org/Enterprise-only — we're on Pro), so a raw Figma/MCP read hands an agent pixel-faithful markup with #1c70ee baked in — the exact friction we want gone (see docs/adr/0016 / north-star).

@bossjob-ds/ds is the owned replacement. It ships to every app repo:

1. A machine-readable component manifest (manifest.json, schema v2) — every @bossjob-ds/* component, its props with allowed enum values, whenToUse / doNotUse, a canonical example, the Figma node it maps to, its dependency graph (composes / requires / dependencies), and a token vocabulary (tokens.groups — the exact valid var(--…) names, role-first).
2. A single rule contract, rendered for three agent tools — "use @bossjob-ds/*
   • tokens, never hardcode hex/px, check the manifest."
3. Two ways to read it — an llms.txt discovery index and a zero-dependency MCP server (npx @bossjob-ds/ds mcp) so agents browse/search/read the contract conversationally instead of grepping JSON.

Together they make an agent's output conformant by construction; the human-facing Conformance Gate checks it after the fact.

What init writes

Run in the root of a consuming app repo:

| File | Purpose | On re-run | |---|---|---| | AGENTS.md | Cross-tool standard (agents.md) | Updated in place (marker-fenced) | | CLAUDE.md | Claude Code project rules | Block injected / updated, your content preserved | | .cursor/rules/bossjob-ds.mdc | Cursor project rule (MDC) | Overwritten (owned file) | | .bossjob/manifest.json | The component manifest the rules point at | Refreshed | | .bossjob/llms.txt | LLM discovery index (routes to the manifest) | Refreshed |

Idempotent: the markdown files carry <!-- BEGIN/END @bossjob-ds/ds --> markers, so re-running after a DS release updates the block in place and never duplicates it.

npx @bossjob-ds/ds init              # wire the current repo
npx @bossjob-ds/ds init --dry-run    # preview, write nothing
npx @bossjob-ds/ds init --dir ./app  # target another directory
npx @bossjob-ds/ds init --force      # overwrite owned files even if locally edited

MCP server

Expose the manifest to any MCP client (Claude Code, Cursor, …) so an agent discovers and reads components conversationally instead of grepping JSON:

npx @bossjob-ds/ds mcp        # stdio Model Context Protocol server (read-only)

Tools: list_components, get_component, search_components, list_tokens, get_manifest_summary. Zero-dependency (hand-rolled stdio JSON-RPC) so it starts instantly under npx. Register it with your client:

{ "mcpServers": { "bossjob-ds": { "command": "npx", "args": ["-y", "@bossjob-ds/ds", "mcp"] } } }

Architecture — "one source, three outputs" (一源三发)

packages/ds/src/contract.mjs            ← THE single source of rule truth
        │  scripts/gen-agent-rules.mjs
        ▼
packages/ds/templates/{AGENTS.md, CLAUDE.snippet.md, cursor-bossjob-ds.mdc}

packages/react (TS types) ─┐
docs/figma/component-map.md │  scripts/gen-manifest.mjs   (TS compiler API)
packages/tokens (CSS vars) ─┘        ▼
                           packages/ds/{manifest.json, llms.txt}

• Prop enums come from the DS TypeScript types, resolved with the real TS compiler — so ButtonSize = 'xxxs'|…|ControlSize flattens to its full literal set, and it can never drift from the code.
• composes / dependencies are auto-derived from each component's source imports (same TS program); whenToUse / example / figmaNodeId / category / requires come from docs/figma/component-map.md, the curated Figma↔code map.
• tokens.groups (the valid var(--…) vocabulary) is generated from @bossjob-ds/tokens — never hand-written.
• Only components present in both code and the map are emitted (manifest stays 1:1 with shipped, documented components).

Regenerating (DS maintainers)

Both generators are deterministic (no timestamps → clean diffs). The outputs are checked in and shipped, so refresh them whenever types, the map, or the contract change:

pnpm --filter @bossjob-ds/ds gen     # rules + manifest
# or individually, from the repo root:
pnpm agent-rules:build            # contract → templates/
pnpm manifest:build               # types + map → manifest.json
pnpm agent-rules:build --check    # CI: fail if templates are stale
pnpm manifest:build --check       # CI: fail if manifest is stale

Consuming the manifest programmatically

import manifest from '@bossjob-ds/ds/manifest.json' with { type: 'json' };
const button = manifest.components.find((c) => c.name === 'Button');
button.props.find((p) => p.name === 'variant').enum;
// → ['primary','secondary','tertiary','ghost','outline','text','danger']

manifest.components.find((c) => c.name === 'ConfirmationDialog').composes;
// → ['Button','Modal']              (auto-derived dependency graph)
Object.keys(manifest.tokens.groups);
// → ['color-role','color-palette','typography','spacing', …]   (valid var(--…) vocabulary)

manifest.schema.json (JSON Schema 2020-12) ships alongside for validation and editor autocomplete.