# For designers

## Day 1 (one hour)

1. **Get the repo locally** so the SVGs are on disk and you can drag them into Figma without proxying through a Slack message.
   ```bash
   git clone git@github.com:mirai-srl/project-ask-design-system.git
   open project-ask-design-system/brand-sheets/Ask\ Brand\ Sheet.html
   ```
2. **Read the prose:** [`brand/guidelines.md`](./brand/guidelines.md) and [`brand/voice-and-tone.md`](./brand/voice-and-tone.md).
3. **Memorize the three environments:** [`brand/environments.md`](./brand/environments.md). When you sit down to design a new surface, the first question you should answer is *"Which environment is this?"*
4. **Mandatory compliance patterns A–D:** [`brand/compliance-patterns.md`](./brand/compliance-patterns.md). If your surface displays agent output or writes to an external system, these are not optional.

## Day 2 — wire Figma to the tokens

Follow [`design-tokens/figma/IMPORT.md`](../design-tokens/figma/IMPORT.md), then [`design-tokens/figma/FIGMA-LIBRARY.md`](../design-tokens/figma/FIGMA-LIBRARY.md) for the full library setup.

The library is split into three files inside the **ASK · Design System** project:

```
01 — Foundations    locked except during version bumps
02 — Components     edited by the owner; reviewed by product designers
03 — Patterns       load-bearing. Contains the three environments + the four compliance patterns
```

Subscribe your product files to all three. Never reinvent — compose from `Patterns`.

## The hard rules

These are non-negotiable. Breaking any of them gets a PR rejected at design review.

- ❌ **No hex codes in frames.** Always bind to a token. If a value isn't a token yet, [open a token-change issue](../.github/ISSUE_TEMPLATE/token_change.yml) — don't paste the hex.
- ❌ **No emoji** in product or marketing surfaces. ASK is a corporate-co-pilot brand, not a casual one.
- ❌ **No rounded corners > 8 px** (`radius.lg`). ASK is sharp.
- ❌ **No "disabled" state for unauthorized actions.** Pattern D — omit, don't gray out.
- ❌ **No single-click submit on external writes.** Pattern B — HITL is structural.
- ❌ **No agent output without inline citation slot.** Pattern A.
- ❌ **No high-saturation accent colors** beyond the Red. The palette is mostly neutral by design.

## The opinionated defaults

These are the conventions you can rely on without checking every time.

| Choice | Default |
|---|---|
| Canvas background | `ask.paper` (`#F7F6F4`) |
| Primary text | `ask.ink` (`#0A0A0A`) |
| Body text | `ask.graphite` (`#2A2A2D`) |
| Borders / dividers | `ask.rule` (`#D8D6D2`) |
| Display font | Archivo Black 900 |
| Body font | Archivo 400 |
| Caption (UPPERCASE) | Archivo 500, 12 px, 0.14em tracking |
| Default radius (UI controls) | `4 px` (`radius.md`) |
| Primary CTA | `state.danger` or `ask.red` — never both in the same surface |
| Motion | `200ms` `ease.standard` for most things |

## Common questions

**"There's no token for the thing I want."**
Good — that means you're at the edge of the system. [Open a token-change issue](../.github/ISSUE_TEMPLATE/token_change.yml) with a real surface that needs it. We add tokens with intent, not preemptively.

**"Can I detach this component?"**
No. If the component doesn't fit, propose a new variant or new component. Detached instances break the system the moment we update the master.

**"How do I show that an action is loading?"**
Use the `loading` boolean property on the relevant component. Don't invent a spinner.

**"How do I push a token change back to git?"**
Tokens Studio → Push to GitHub. Setup once in [`design-tokens/figma/FIGMA-LIBRARY.md` §6.3](../design-tokens/figma/FIGMA-LIBRARY.md). Opens a PR.

**"My product manager wants a softer red."**
The red is the brand. We don't soften it for a campaign. Use `ask.red-soft` for washes, or use a neutral accent.

## The cheat sheet

```
Open the brand sheet                 → brand-sheets/Ask Brand Sheet.html
Open the component reference         → brand-sheets/Ask Design System.html
Find a token                         → design-tokens/tokens.json
Add a token                          → issue: token_change.yml
Add a component                      → issue: component_request.yml
Push token change Figma→Git          → Tokens Studio "Push to GitHub"
Subscribe to library updates         → Assets panel → Libraries
Get a logo                           → logo/  (drag SVG into the frame)
Compose a citation, HITL, guardrail  → 03 — Patterns / compliance/*
```