# For engineers

## Day 1 (thirty minutes)

```bash
# 1. Clone
git clone git@github.com:mirai-srl/project-ask-design-system.git
cd project-ask-design-system

# 2. Install dev deps for the token tooling
pnpm install

# 3. Verify the source-of-truth → derived chain
pnpm run tokens:validate   # DTCG shape correctness
pnpm run tokens:check      # drift check across consumers
pnpm run tokens:build      # writes dist/ artifacts

# 4. Open the visual reference
open "brand-sheets/Ask Design System.html"
```

## Consuming the tokens in a product repo

### Option A — git submodule (recommended)

Best when your product repo wants the canonical files always-fresh and locked to a tag.

```bash
# In the product repo:
git submodule add -b main \
  git@github.com:mirai-srl/project-ask-design-system.git \
  packages/brand
git submodule update --init --recursive

# Pin to a release tag for deterministic builds
cd packages/brand
git checkout ask-design@1.0.0
```

Then in your `tailwind.config.ts`:

```ts
import askPreset from './packages/brand/design-tokens/shadcn/tailwind.preset';
export default { presets: [askPreset], content: ['./src/**/*.{ts,tsx}'] };
```

And in your global stylesheet:

```css
@import './packages/brand/design-tokens/shadcn/globals.css';
```

### Option B — copy + sync via Renovate

Pin to a release artifact (`ask-design-system-1.0.0.tar.gz` from the release page), unpack into `packages/brand/`, let Renovate track the tag for upgrade PRs.

### Option C — npm-style import (when published)

The repo is not published to npm. If you need that, file an [infra issue](https://github.com/mirai-srl/project-ask-design-system/issues/new) and we'll set up a private GitHub Packages registry.

## What lives in code vs. in Figma

| Concern | Source of truth |
|---|---|
| Color / type / spacing / radius / motion values | `design-tokens/tokens.json` |
| Figma variables and styles | `design-tokens/figma/tokens-studio.json` (derived) |
| Component implementation | **shadcn** (your repo) — Figma is parallel doc |
| Component visual spec | Figma `02 — Components` file |
| Compliance pattern spec | `docs/brand/compliance-patterns.md` |

There is no automated Figma-component → shadcn-code sync. The discipline is: every new shadcn component must have a Figma counterpart, and vice versa. PR reviewers check the link.

## The four hard rules in code

| Rule | How to enforce in code |
|---|---|
| **Pattern A — citation** | Any component that renders model output (`<Message />`, `<AnswerBlock />`) must accept and render a `citations` prop. No exceptions. Lint rule lives in your product repo. |
| **Pattern B — HITL** | Single-click submit handlers that POST to external systems are forbidden. Use the `<SlideToApprove />` primitive (which lives in your product repo) or a multi-checkbox confirm sheet. Code review CC: `@ask-security`. |
| **Pattern C — guardrail** | Guardrail responses render via the `<Guardrail />` component with `tone={'active'|'block'}`. Don't render them as toasts; they're inline. |
| **Pattern D — RBAC** | Never render an unauthorized action with `disabled={true}`. Filter the option out of the menu/array entirely. Lint rule: forbid `disabled` on action items derived from RBAC selectors. |

## Local dev loop

```bash
# Edit a token
$EDITOR design-tokens/tokens.json

# Validate
pnpm run tokens:validate

# Update the curated consumer file by hand to match — globals.css uses HSL
# channel notation (354 78% 52%, not hsl(354, 78%, 52%)).
$EDITOR design-tokens/shadcn/globals.css

# Confirm parity
pnpm run tokens:check

# Generate dist/ outputs
pnpm run tokens:build

# Commit
git add -A
git commit -m "feat(tokens): add ask.color.state.processing"
```

## CI matrix

| Workflow | Trigger | What it gates |
|---|---|---|
| [`ci.yml`](../.github/workflows/ci.yml) | every push & PR | Lint, format, token validate, token drift, HTML well-formedness, link check |
| [`tokens-build.yml`](../.github/workflows/tokens-build.yml) | changes under `design-tokens/` | Regenerates `dist/`, fails if anything would change |
| [`chromatic.yml`](../.github/workflows/chromatic.yml) | every push & PR (non-fork) | Visual regression on Storybook build |
| [`release.yml`](../.github/workflows/release.yml) | tag `ask-design@*` | Bundles the release tarball, publishes GitHub release |

## Where things live

```
design-tokens/tokens.json              source of truth
design-tokens/shadcn/globals.css       curated CSS vars (HSL channels)
design-tokens/shadcn/tailwind.preset.ts curated Tailwind preset
design-tokens/storybook/theme.ts       curated Storybook theme
design-tokens/figma/tokens-studio.json curated Figma plugin input
dist/                                  generated by tokens:build (gitignored)
scripts/                               build, check, validate
```

If your product repo has its own shadcn directory, mirror the file structure inside `packages/brand/` so engineers know exactly where to look.