TCRN Design System

Package-backed UI primitives, tokens, copy-state vocabulary, and Storybook contract docs for TCRN product frontends.

English · 简体中文 · 日本語 · 한국어 · Français

What This Repo Is

This repository is the TCRN Design System source-control home. It contains the package-backed UI baseline plus the static Storybook contract surface that AI agents, product frontend implementers, and reviewers must read before claiming Design System compliance.

The hosted Storybook is available at tcrn-design-system-storybook.vercel.app. That URL is a hosted readback for the static docs surface; package publication, hosted-doc readiness, product adoption, release readiness, and product acceptance remain separate routes.

Packages

• @tcrn/ui-tokens: semantic token metadata, CSS variables, and light/dark theme token overrides.
• @tcrn/ui-copy-state: supported locales, copy-state vocabulary, and no-overclaim display helpers.
• @tcrn/ui-react: package-backed React primitives for shared UI presentation and accessibility.
• apps/storybook: static contract docs, synthetic stories, proof fixtures, and the machine-readable AI contract.

Storybook Contract Docs

• Default docs: Storybook home
• Chinese reader path: Storybook zh-CN
• Dark shell proof path: Storybook dark mode
• AI contract story: Proof / AI consumption contract

The Storybook surface is static and synthetic. It is the shared contract map for tokens, copy, components, patterns, no-overclaim language, and local proof expectations. It does not prove AOS or TMS product adoption by itself.

AI Consumption Contract

AI and product frontend agents must read the Storybook AI contract before implementation:

• Static artifact: apps/storybook/storybook-static/ai-consumption-contract.json
• Hosted artifact: ai-consumption-contract.json
• AI-first plain-text entry: llms.txt
• Story route: proof.html#ai-consumption-contract
• HTML head discovery: every static Storybook page points to the JSON contract and llms.txt.
• Required AI readback fields: contractVersion, contractPayloadDigest, artifact, route, readAt, coveredRules, requiredProof, noOverclaimBoundaries.

The contract requires package-backed Design System imports, approved locale/copy-state handling, admitted brand assets or a brand admission route, token/accessibility usage, and explicit light/dark shell proof before downstream compliance claims.

Supported Locales

The package-backed locale contract supports zh-CN, en, ja, ko, and fr; the fallback locale is en.

GitHub reader summaries are provided in this README set, and the Storybook shell can switch locale at runtime with ?locale=zh-CN, ?locale=en, ?locale=ja, ?locale=ko, or ?locale=fr.

Theme And Dark Mode

The Storybook docs shell supports light and dark modes through semantic tokens. Use the shell control or ?theme=dark to inspect dark mode. Theme changes must not fork component behavior, locale copy, readiness copy, or brand assets.

Brand And Logo Boundary

The TCRN brand mark and lockups in Storybook are visual-review guidance. Product implementations may use admitted brand assets only, or route a brand component admission before product use. The brand examples in Storybook are not package-backed brand component exports and do not claim final brand acceptance.

Verification Commands

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm storybook:smoke
node --test scripts/readme-public-contract.test.mjs
pnpm storybook:visual-proof -- --check
pnpm public-output:scan
pnpm scan
pnpm verify

No-Overclaim Boundaries

• No npm/package publication is claimed by this README.
• No Storybook/docs publication readiness is claimed by this README.
• No hosted-doc readiness, product adoption, release readiness, product acceptance, final MVP acceptance, or AOS/TMS adoption is claimed here.
• GitHub releases in this repo are source-control checkpoints unless a separate package publication route proves otherwise.