@cyberskill/design 1.0.0

package/llms.txt

@@ -0,0 +1,70 @@
+# CyberSkill Design System
+
+> HTML-first, Vietnamese-first design system, pinned **v1.0.0**. Immutable anchors: Umber #45210E · Ochre #F4BA17. Three independent axes — Theme (light · dark) × Element (Ngũ Hành, 15 variants) × Language (EN · VI); surface treatment is liquid-glass (fixed). It ships 99 components / 115 exports, 84 copyable templates (EN·VN for emails + team/legal/finance; client/media collateral EN-first), and tokens in CSS + JSON + ESM + W3C DTCG + native mirrors. This file is the agent/tool front door: it maps each audience to the format it should consume. npm package name is **`@cyberskill/design`** (not `@cyberskill/react`). Release signal: tip SHA + [docs/release-notes.md](docs/release-notes.md) — no CHANGELOG.
+
+The portable contract (styles.css · `_esm/cs.mjs` · bundle · tokens) works everywhere; the DC layer (`templates/**/*.dc.html`) is **Claude Design / authoring-environment-only**. **Google Stitch must not treat `*.dc.html` as source of truth** — use `DESIGN.md`, DTCG, `styles.css`, kitchen-sink, and `.cs-*` static HTML instead. Dual path: [docs/consuming.md](docs/consuming.md). The full non-negotiables list lives in `CONTRIBUTING.md` and `docs/conventions.md`.
+
+## Consume by audience
+
+- **Claude Code** → [SKILL.md](SKILL.md) first, then [README.md](README.md): compose with `styles.css` + `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve). Optional DC templates only when the session has the compiler. Gates/`_audit/` need a full clone.
+- **Google Stitch** → [DESIGN.md](DESIGN.md) first, then this file + [tokens/tokens.dtcg.json](tokens/tokens.dtcg.json): generate **static** UI. Do **not** open or rewrite `templates/**/*.dc.html` as if they were plain HTML.
+- [styles.css](styles.css): any web / framework / email (Vue, Svelte, plain HTML, React) — link this one file for every `--cs-*` token, the `.cs-*` component classes, and the Liquid Glass surfaces. Framework-agnostic, no build step.
+- [_esm/cs.mjs](_esm/cs.mjs): ESM React entry — `import { Button, … } from "./_esm/cs.mjs"` (still link `styles.css`).
+- [_ds_bundle.js](_ds_bundle.js): React (production) — `styles.css` + `<script src="_ds_bundle.js">`, then resolve the bundle global by prefix (its `_<projectId>` suffix is compiler-assigned and changes on re-import): `const CS = window[Object.keys(window).find(k => /^CyberSkillDesignSystem_/.test(k))]; const { Button, … } = CS`. Proven green by `_audit/consumer-smoke-test.html`. (Templates load via `ds-base.js`, which publishes a stable `window.CyberSkillDS` alias for the same reason.)
+- [tokens/tokens.json](tokens/tokens.json): design tools / native / token pipelines / other agents (Figma, Google Stitch, Style Dictionary) — every token grouped by category, plus theme/element override maps; also [tokens/tokens.js](tokens/tokens.js) (ESM) and [tokens/tokens.dtcg.json](tokens/tokens.dtcg.json) (**W3C DTCG** format for Tokens Studio for Figma / Style Dictionary). This is the canonical cross-tool contract.
+- [DESIGN.md](DESIGN.md): agents/tools that read a root DESIGN.md (Google Stitch open-spec style) — **this repo's** generated file with the brand doctrine, every token value (light + dark), and the component/template inventory. Generated from the DTCG source by `npm run build:design-md`; the `design-md-parity` gate pins it — do not hand-edit.
+- [templates/](templates/): Design Components (`templates/**/*.dc.html`) + the compiler (tweaks, `x-import`, `@dsCard` cards) for **Claude Design** only. Stitch and other non-DC tools: [templates/kitchen-sink.html](templates/kitchen-sink.html) + `.cs-*` / [examples/static-hello/](examples/static-hello/) — **not** `*.dc.html`.
+
+## Key files
+
+- [dashboard.html](dashboard.html): legacy redirect stub → `/` (product site is Storybook)
+- [styles.css](styles.css): single entry point (`@import`s `tokens/` then `base/`)
+- [_esm/cs.mjs](_esm/cs.mjs): ESM entry (imports every component, no build)
+- [tokens/](tokens/): design tokens as CSS custom properties + `tokens.json` / `tokens.js` / `tokens.dtcg.json` (W3C DTCG) + `viewer.html` (table + raw modes) + `native/` (SwiftUI/Compose/Flutter)
+- [base/](base/): reset, component classes (`.cs-*`), a11y, responsive, glass
+- [components/](components/): 99 components / 115 exports — every primary ships `.jsx` + `.d.ts` + `.prompt.md` + a `@dsCard` card; co-exports are documented in their parent's files
+- [templates/](templates/): 84 copyable starting points (`.dc.html`); `email-safe/` send-ready emails; `kitchen-sink.html`; `playground.html`
+- [guidelines/](guidelines/): specimen cards + `atomic-view.html` (portable component grid) — host product surface is Storybook at `/`
+- [ui_kits/](ui_kits/): product recreations — status-hub · website · deck
+- [fonts/](fonts/): self-hosted Be Vietnam Pro + JetBrains Mono woff2
+- [assets/](assets/): official logo mark (never recreate) · favicon · aurora washes · Lumi mascot
+- [README.md](README.md): the entrance document — voice, visual foundations, components, templates, index
+- [DESIGN.md](DESIGN.md): generated open-spec surface (doctrine + tokens + inventory) for Stitch-style consumers — pinned to DTCG by the design-md-parity gate
+- [SKILL.md](SKILL.md): agent entry — hard rules + fast orientation
+- [CONTRIBUTING.md](CONTRIBUTING.md): one-page onboarding for extending the system
+- [VERSION](VERSION): pinned 1.0.0 (matches [package.json](package.json))
+
+## Docs — consumers
+
+- [docs/consuming.md](docs/consuming.md): adopting & upgrading, Claude Code vs Stitch dual path, package name `@cyberskill/design`
+- [docs/release-notes.md](docs/release-notes.md): curated product highlights (not a changelog)
+- [docs/conventions.md](docs/conventions.md): authoring rules (naming grammar, the three axes)
+- [docs/design-styles.md](docs/design-styles.md): the live styling axes and the fixed liquid-glass treatment
+- [docs/products.md](docs/products.md): product → element registry (**locked**)
+- [docs/contrast-report.md](docs/contrast-report.md): generated APCA elemental sweep — 0 failures at its Lc ≥ 60 UI-label floor (body text authors to Lc ≥ 75)
+- [docs/template-schema-v2.md](docs/template-schema-v2.md): typed content-slot spec for templates
+- [docs/deploy.md](docs/deploy.md): deploying the live site (Vercel / VPS / any static host)
+- [docs/live-hub.md](docs/live-hub.md): Storybook at `/` is the product surface; surface map
+- [docs/storybook.md](docs/storybook.md): host Storybook product surface at `/`
+- [docs/figma.md](docs/figma.md): Figma / Tokens Studio import recipe
+- [docs/vi/](docs/vi/): Vietnamese mirror of every operator-facing `docs/*.md`
+- [docs/viewer.html](docs/viewer.html): reader UI (EN|VI toggle for `docs/*.md`)
+
+## Docs — maintainers
+
+- [docs/decisions.md](docs/decisions.md): recorded owner decisions + open maintainer tasks
+- [docs/ci-cd.md](docs/ci-cd.md): CI/CD automation — workflow, headless gate runner, provenance pre-check
+- [docs/quality-gates.md](docs/quality-gates.md): benchmark reference — every quality gate, its assertion, pass criterion, where it runs
+- [docs/sync.md](docs/sync.md): repo ↔ authoring-environment round-trip fidelity & two-way sync
+- [_audit/archive/](_audit/archive/): historical audit notes (not public docs)
+
+## Non-negotiables
+
+- [CONTRIBUTING.md](CONTRIBUTING.md): the full non-negotiables list (with `docs/conventions.md`)
+- [tokens/colors.css](tokens/colors.css): immutable Umber/Ochre anchors · one accent per surface
+- [base/a11y.css](base/a11y.css): APCA Lc ≥ 75 body text · ≥44px touch targets · 3px ochre focus ring · honour `prefers-reduced-motion`/`prefers-contrast`
+- [docs/conventions.md](docs/conventions.md): Vietnamese-first bilingual — every UI string ships an EN + VN pair, diacritics preserved
+
+## Sync
+
+- [docs/sync.md](docs/sync.md): repo is the source of truth — pull the whole tree at session start and commit back via PR at session end

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@cyberskill/design",
+  "version": "1.0.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "module": "_esm/cs.mjs",
+  "exports": {
+    ".": {
+      "import": "./_esm/cs.mjs"
+    },
+    "./styles.css": "./styles.css",
+    "./tokens/*": "./tokens/*",
+    "./_ds_bundle.js": "./_ds_bundle.js",
+    "./_ds_manifest.json": "./_ds_manifest.json"
+  },
+  "description": "CyberSkill Design System — HTML-first, Vietnamese-first (EN·VI). Anchors: Umber #45210E · Ochre #F4BA17. Axes: Theme × Element × Language. No build step: styles.css + _ds_bundle.js. Storybook is host-only playground.",
+  "style": "styles.css",
+  "files": [
+    "styles.css",
+    "_esm/",
+    "tokens/",
+    "base/",
+    "fonts/",
+    "assets/",
+    "_ds_bundle.js",
+    "_ds_manifest.json",
+    "llms.txt",
+    "SKILL.md",
+    "docs/",
+    "components/",
+    "templates/",
+    "guidelines/",
+    "ui_kits/",
+    "DESIGN.md",
+    "VERSION"
+  ],
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "bilingual",
+    "vietnamese",
+    "cyberskill"
+  ],
+  "license": "UNLICENSED",
+  "type": "module",
+  "scripts": {
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "build:design-md": "node scripts/generate-design-md.mjs",
+    "prepublishOnly": "npm run build:bundle && node scripts/generate-design-md.mjs --check",
+    "code-connect:generate": "node _audit/ci/generate-code-connect.mjs",
+    "code-connect:dry-run": "node _audit/ci/code-connect-publish.mjs --dry-run",
+    "npm:pack-dry-run": "node _audit/ci/npm-publish.mjs --dry-run",
+    "native:store-dry-run": "node _audit/ci/native-store-dry-run.mjs --dry-run",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build -o storybook-static",
+    "build:site": "npm run build:storybook && node scripts/vercel-static-output.mjs",
+    "verify:serve": "python3 -m http.server 8765 --bind 127.0.0.1",
+    "verify:hint": "echo Open http://127.0.0.1:8765/_audit/run.html and wait for ALL hard gates PASS",
+    "verify:local": "bash scripts/verify-local.sh",
+    "test:nav-model": "node _audit/ci/test-nav-model.mjs",
+    "test:ui-contracts": "node _audit/ci/test-health-tokens-contract.mjs",
+    "test:form-paths": "node _audit/ci/test-form-paths.mjs",
+    "test:unit": "node _audit/ci/test-nav-model.mjs && node _audit/ci/test-health-tokens-contract.mjs && node _audit/ci/test-form-paths.mjs && node _audit/ci/test-storybook-contract.mjs && node _audit/ci/test-figma-push-helpers.mjs && node _audit/ci/test-native-samples.mjs && node _audit/ci/test-code-connect.mjs && node _audit/ci/test-subtree-consume.mjs",
+    "test:subtree-consume": "node _audit/ci/test-subtree-consume.mjs",
+    "native:sync-tokens": "node examples/native/sync-tokens.mjs",
+    "test:storybook-contract": "node _audit/ci/test-storybook-contract.mjs",
+    "test:storybook-coverage": "node _audit/ci/test-storybook-contract.mjs",
+    "test:figma-helpers": "node _audit/ci/test-figma-push-helpers.mjs",
+    "test:code-connect": "node _audit/ci/test-code-connect.mjs",
+    "test:native-samples": "node _audit/ci/test-native-samples.mjs"
+  },
+  "devDependencies": {
+    "@figma/code-connect": "^1.4.9",
+    "@storybook/addon-a11y": "^10.5.3",
+    "@storybook/addon-docs": "^10.5.3",
+    "@storybook/react": "^10.5.3",
+    "@storybook/react-vite": "^10.5.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.47.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^10.5.3",
+    "vite": "^5.4.11"
+  }
+}

package/styles.css

@@ -0,0 +1,39 @@
+/* CyberSkill Global Design System — single entry point.
+ * Consumers link THIS file. It is an @import manifest only: fonts, then design
+ * tokens, then base component + surface styles. Turn Your Will Into Real.
+ *
+ * Anchors are immutable: Umber #45210E · Ochre #F4BA17 · Vietnamese-first ·
+ * voice = warm / direct / honest / respectful · APCA Lc >= 75 body text. */
+
+/* 1 — Webfonts (must precede token/style rules) */
+@import url("tokens/fonts.css");
+
+/* 2 — Design tokens */
+@import url("tokens/colors.css");
+@import url("tokens/typography.css");
+@import url("tokens/spacing.css");
+@import url("tokens/elevation.css");
+@import url("tokens/motion.css");
+@import url("tokens/component-tokens.css");
+@import url("tokens/elements.css");
+
+/* 3 — Base: reset, type utilities, component classes, Liquid Glass surfaces */
+@import url("base/reset.css");
+@import url("base/typography.css");
+@import url("base/components.css");
+@import url("base/forms.css");
+@import url("base/feedback.css");
+@import url("base/data.css");
+@import url("base/navigation.css");
+@import url("base/ai.css");
+@import url("base/controls.css");
+@import url("base/collections.css");
+@import url("base/shell.css");
+@import url("base/glass.css");
+@import url("base/interaction.css");
+
+/* 3.5 — Accessibility: coarse-pointer 44px targets + reduced-motion safety net */
+@import url("base/a11y.css");
+
+/* 4 — Global responsive layer (loaded last; adapts every surface to tablet/phone) */
+@import url("base/responsive.css");