@gracemgoud/ds-test

A custom design tokens package that overrides Untitled UI's default brand color scale with a blue palette (#2D67B5 as the primary). Built with Style Dictionary v4 and distributed as a CSS override layer.

⚠️ Prerequisite: Untitled UI must be installed first

This package is an override layer, not a standalone library. It only works on top of Untitled UI. If Untitled UI isn't installed in your project, this package will have nothing to override and won't appear to do anything.

In a fresh project (Figma Make, Next.js, Vite, etc.), bootstrap Untitled UI first:

# Initialize the project — adds theme.css, typography.css, Tailwind config, utils
npx untitledui@latest init

# Add the components you need
npx untitledui@latest add button input badge avatar checkbox toggle featured-icon

After running these, your project should have:

• src/components/base/, src/components/foundations/ (or wherever Untitled UI scaffolds them)
• src/styles/theme.css — Untitled UI's default tokens (this is what ds-test overrides)
• src/styles/typography.css

Don't install @gracemgoud/ds-test until those exist.

Install

Once Untitled UI is in place:

npm install @gracemgoud/ds-test

Wire the override layer

In your project's main stylesheet (usually src/styles/globals.css):

@import "tailwindcss";
@import "./theme.css";                     /* Untitled UI's defaults */
@import "@gracemgoud/ds-test/brand.css";   /* override layer — must come after theme.css */
@import "./typography.css";

Order matters. The DS-Test import must come after Untitled UI's theme.css, otherwise the override won't take effect.

That's it. Every Untitled UI component that uses the brand scale (Buttons in color="primary", BadgeWithDot in color="brand", FeaturedIcon in color="brand", etc.) automatically picks up the new blue. No component-level styling needed.

What it changes

The package overrides these CSS custom properties:

| Token | Value | |---|---| | --color-brand-25 | rgb(251 252 254) — lightest tint | | --color-brand-50 | rgb(244 247 251) | | --color-brand-100 | rgb(229 237 246) | | --color-brand-200 | rgb(192 209 233) | | --color-brand-300 | rgb(150 179 218) | | --color-brand-400 | rgb(98 141 200) | | --color-brand-500 | rgb(56 111 185) | | --color-brand-600 | rgb(45 103 181) — primary brand (#2D67B5) | | --color-brand-700 | rgb(36 82 145) | | --color-brand-800 | rgb(29 67 118) | | --color-brand-900 | rgb(23 52 91) | | --color-brand-950 | rgb(14 31 54) — darkest shade |

Usage in code (correct vs. incorrect)

✅ Correct — use semantic tokens, let the override layer handle the color:

import { Button } from "@/components/base/buttons/button";

<Button color="primary">Save</Button>
<div className="bg-brand-solid text-primary_on-brand">Hero</div>

❌ Incorrect — never type the hex value or use raw Tailwind colors:

<button style={{ background: "#2D67B5" }}>Save</button>
<div className="bg-blue-600 text-white">Hero</div>

Updating tokens (for maintainers)

Tokens are defined in src/brand.tokens.json. To change them:

1. Edit src/brand.tokens.json
2. Build: npm run build (regenerates dist/brand.css and dist/tokens.json)
3. Bump: npm version patch (or minor / major per semver)
4. Publish: npm publish
5. Consumers update with: npm update @gracemgoud/ds-test

Edits are never made downstream in consuming projects — change once here, propagate everywhere.

What's in the package

@gracemgoud/ds-test/
├── src/
│   └── brand.tokens.json     # source of truth (edit this)
├── dist/
│   ├── brand.css             # the override layer your project imports
│   └── tokens.json           # flat machine-readable export (Figma sync, etc.)
└── README.md

Adding more tokens

Drop another file like src/typography.tokens.json into src/. The build script's source glob (src/**/*.tokens.json) picks it up automatically.

If you need additional output formats (separate CSS file, Swift constants, Android XML), extend scripts/build.mjs with a new platform block.

License

MIT.