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 rules
• docs/components.md: every component's props, events, slots, and HTML and React examples
• docs/tokens.md: design tokens and which ones to use
• llms.txt: index of the above; docs/custom-elements.json is 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

Prefixes

| Kind | Convention | Example | |------|------------|---------| | Custom elements | ads- tag | <ads-button> | | CSS classes | ads- BEM | .ads-button, .ads-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/ads-button';
import '@addaab/ads/css'; // or `@addaab/ads/css/ads-button` + `@addaab/ads/tokens/css`

defineCustomElement();

<ads-button variant="primary">Open account</ads-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 { AdsButton } from '@addaab/ads/react';
import '@addaab/ads/css';

<AdsButton variant="primary">Open account</AdsButton>

Per-component: import { AdsButton } from '@addaab/ads/react/ads-button'.

3. CSS only (vanilla HTML)

<button class="ads-button ads-button--primary ads-button--medium" type="button">Open account</button>

import '@addaab/ads/css/ads-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 | .ads-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/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.