Adda Design System (@addaab/ads)
Design tokens, Stencil web components, generated React wrappers, and CSS — shipped as one installable package.
For AI agents (Claude Code, Claude Design, Lovable, v0, Cursor …)
Read these before generating code with this package (they ship inside it):
AGENTS.md: required setup (CSS, Avenir Next font), React patterns, server-rendered pages (markup contract), component catalogue, host page CSS and rulesUPGRADING.md: migration guide for breaking releases, with a codemod. 1.0.0 renames theads-prefix todsa-docs/components.md: every component's props, events, slots, and HTML and React examplesdocs/tokens.md: design tokens and which ones to usellms.txt: index of the above;docs/custom-elements.jsonis the Custom Elements Manifest
Install
npm install @addaab/ads
For the React wrappers, also install their peer dependencies:
npm install @stencil/react-output-target react react-dom
@stencil/react-output-target is marked as an optional peer dependency (CSS-only and custom-element consumers don't need it), but the React wrappers import @stencil/react-output-target/runtime at runtime. React apps must install it explicitly; without it you get Cannot find module '@stencil/react-output-target/runtime'.
Prefixes
| Kind | Convention | Example |
|---|---|---|
| Custom elements | dsa- tag | <dsa-button> |
| CSS classes | dsa- BEM | .dsa-button, .dsa-button--primary |
| Token CSS variables | Figma export names (unchanged) | --component-color-…, --alias-… |
Consumption modes
1. Vite + custom elements (preferred)
Tree-shakeable: import only what you use, then register that element.
import { defineCustomElement } from '@addaab/ads/components/dsa-button';
import '@addaab/ads/css'; // or `@addaab/ads/css/dsa-button` + `@addaab/ads/tokens/css`
defineCustomElement();
<dsa-button variant="primary">Open account</dsa-button>
React wrappers call defineCustomElement for you.
2. React (generated wrappers)
React bindings are produced by @stencil/react-output-target during the Stencil build. Do not hand-maintain them.
import { DsaButton } from '@addaab/ads/react';
import '@addaab/ads/css';
<DsaButton variant="primary">Open account</DsaButton>
Per-component: import { DsaButton } from '@addaab/ads/react/dsa-button'.
3. CSS only (vanilla HTML)
<button class="dsa-button dsa-button--primary dsa-button--medium" type="button">Open account</button>
import '@addaab/ads/css/dsa-button';
import '@addaab/ads/tokens/css';
4. Lazy loader (no bundler)
import { defineCustomElements } from '@addaab/ads/loader';
defineCustomElements();
Prefer mode 1 with Vite.
Package exports
| Import | Purpose |
|---|---|
@addaab/ads/components/<name> | Custom element module (auto-defines) |
@addaab/ads/react | Generated React wrappers |
@addaab/ads/css | Tokens + all component CSS |
@addaab/ads/css/<name> | Single component CSS |
@addaab/ads/tokens | Token JSON |
@addaab/ads/tokens/css | Token CSS variables |
@addaab/ads/tokens/typography | .dsa-type-* typography classes (included in @addaab/ads/css) |
@addaab/ads/tokens/js | Token list as JS (tokens array: path, CSS variable, value) |
@addaab/ads/AGENTS.md | Consumer guide for AI agents and developers |
@addaab/ads/UPGRADING.md | Migration guide for breaking releases (1.0.0: ads- → dsa-) |
@addaab/ads/codemods/migrate-to-dsa.mjs | Codemod for the 1.0.0 rename (node … <dir> --write) |
@addaab/ads/docs/* | Generated API reference (components.md, tokens.md, custom-elements.json) |
@addaab/ads/loader | Stencil lazy loader |
Light DOM policy
Components use light DOM by default (shadow: false) for SEO and accessibility. Use shadow DOM only when a component needs strong isolation; that component's readme documents the reason.
Source & contributing
Source, issue tracking, and contribution docs live in the Adda Design System Azure DevOps repo (packages/ads). See docs/RELEASING.md there for how releases are cut.