@dig-ai/design-system

Dig's component library: canonical shadcn/ui components restyled onto the Dig design tokens, published to npm for any React app.

• Using it in an app? → INTEGRATION.md
• An AI agent working in a consuming app? → AGENTS.md
• Working on this repo? → keep reading

npm install @dig-ai/design-system

What this is, precisely

Components are generated by the real shadcn CLI — npx [email protected] add … — and then mechanically restyled. Both halves of that matter:

• The public API is unchanged — variant="outline", size="icon", asChild, data-slot, and the same composition shapes. Anyone who knows shadcn already knows this library, and agents generate correct code without being taught.
• Only the internal classes change: bg-primary → bg-dig-primary, so the package can never collide with a consuming app's own Tailwind theme.
• dark: styles are stripped. This version ships the Enterprise (light) theme only.

The restyle is a script, not a set of hand edits, so taking an upstream fix is npm run vendor -- --force and reading the diff — not redoing 24 files by hand.

npm run vendor shells out to the pinned shadcn CLI rather than fetching registry JSON itself. Fetching would mean reimplementing what the CLI does — style resolution for the installed Tailwind version, import-alias rewriting, per-release transforms — and maintaining that fork forever. To give the CLI somewhere to install, the script writes a throwaway project in a temp directory and reads the files back out; none of it ships.

Two settings in that staging components.json are load-bearing, and one bit us:

• rsc: true. With rsc: false the CLI strips "use client" from client components, which is right for a plain SPA and wrong for a published library — it silently removed the directive from eight components until this was corrected.
• aliases mirror this repo's own, so the CLI's emitted imports need no rewriting.

Everything generated, and from what

Almost nothing in this repo is hand-maintained. Each arrow is a script that fails loudly rather than emitting something approximate.

tokens/ds-tokens.md            (vendored from product-workflows)
  └─ npm run tokens:import  ─> tokens/tokens.json
       └─ npm run tokens:generate ─> src/theme/theme.css      (@theme + @utility)
                                     src/theme/tokens.ts      (typed values)

npx [email protected] add …         (the CLI, run against a temp staging project)
  └─ npm run vendor         ─> src/components/ui/*.tsx        (restyled)
                               tokens/shadcn.lock.json        (CLI output hashes)

src/components/ui/*.tsx + docs/catalog-docs.json
  └─ npm run catalog:generate ─> catalog.json                 (agent inventory)
                                 src/index.ts                 (barrel)
                                 AGENTS.md                    (inventory table)

Consequences worth knowing before you edit anything:

• Do not edit src/components/ui/*.tsx by hand. Change scripts/vendor-shadcn.mjs and re-vendor, or the next sync silently reverts you.
• Do not edit src/theme/theme.css, src/theme/tokens.ts, src/index.ts, catalog.json, or the inventory block in AGENTS.md. All generated.
• Do edit docs/catalog-docs.json — descriptions, examples and "use X instead" guidance are editorial and cannot be derived from source.

npm run verify re-runs every generator with --check and fails if a committed artifact disagrees with its source, so a forgotten regeneration cannot merge.

Layout

tokens/         vendored ds-tokens.md, generated tokens.json, shadcn.lock.json
scripts/        the pipelines above, plus build-output guards
src/
  components/ui/  the 24 vendored components (generated)
  theme/          theme.css + tokens.ts (generated), fonts.css (hand-written)
    fonts/          bundled Manrope (OFL) + licence — beside fonts.css so its
                    relative URLs resolve the same in source and in dist
  lib/utils.ts    cn(), with the tailwind-merge config the override contract needs
  index.ts        barrel (generated)
styles/build.css  entry compiled into dist/styles.css
docs/             catalog-docs.json — the editorial half of the catalog
tests/            component, SSR/hydration, and contract tests
fixtures/ssr-app/ minimal server-render smoke test against the built package

Working on it

npm install
npm run build          # generate, bundle, compile CSS, check the output
npm test               # 166 tests
npm run verify         # everything CI runs
npm run storybook      # the component playbook

Common tasks:

| Task | Command | Then | | ----------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------- | | Take upstream shadcn fixes | npm run vendor -- --force | read the diff carefully | | Add a component | add it to COMPONENTS in scripts/vendor-shadcn.mjs, add an entry to docs/catalog-docs.json | npm run vendor && npm run catalog:generate | | Update tokens | replace tokens/ds-tokens.md, update tokens/SOURCE.md | npm run tokens:import && npm run tokens:generate | | Change how a colour maps | edit COLOR_MAP in scripts/generate-theme.mjs | npm run tokens:generate | | Change how shadcn classes translate | edit COLOR_ROOTS in scripts/vendor-shadcn.mjs | npm run vendor -- --force |

Known gaps

Being explicit about these so nobody discovers them the hard way:

• Typography is not token-generated. ds-tokens.md is a variable export and carries no text styles, so the type ramp lives in a TYPE_RAMP constant in scripts/generate-theme.mjs sourced from the product theme. Every colour, radius and breakpoint is generated. When the DS publishes text styles as variables, move them.
• Enterprise mode only. tokens.json already carries the Ask.dig and Dark palettes; the generator emits Enterprise. Dark mode also needs the dark: variants we currently strip, and secondary/* is unresolved in the source's Dark mode.
• npm run vendor:check hits the network and is therefore not part of verify. It runs on a schedule in CI instead, so upstream drift shows up as a notification rather than a random build failure.
• No visual regression testing. Storybook is the playbook; nothing diffs pixels yet.

Licence

Proprietary, licensed for internal Dig use — see LICENSE. The package is published to the public registry for distribution convenience, not as open source, so the licence grant is what makes Dig and Lovable-hosted apps legitimate consumers.

Redistributed third-party material and its obligations are set out in THIRD-PARTY-NOTICES.md: component source derived from shadcn/ui (MIT) and the bundled Manrope typeface (SIL OFL 1.1). Both notices ship inside the tarball, enforced by a contract test.