# ASK — Brand & Design System

> Cognitive infrastructure for the enterprise. The brand, voice, tokens, components and patterns that make every ASK surface feel like one product.

[![License: Proprietary](https://img.shields.io/badge/license-Proprietary-0A0A0A)](./LICENSE)
[![Tokens](https://img.shields.io/badge/tokens-DTCG%20v1-E42438)](./design-tokens/tokens.json)
[![Status: Approved](https://img.shields.io/badge/status-approved-1F8A5B)](./docs/brand/guidelines.md)
[![Version](https://img.shields.io/badge/version-1.0.0-2A6FDB)](./CHANGELOG.md)

---

## What's in this repo

ASK ships its brand, design language, and engineering primitives as a single versioned package. This repository is the **source of truth** for everything visual and tonal in the product — from the wordmark to the four mandatory compliance patterns.

```
.
├── design-tokens/        DTCG tokens → Figma, Tailwind, Storybook artifacts
├── logo/                 SVG + PNG marks (knockout, on-white, mark-only…)
├── docs/                 Brand guidelines, voice & tone, environments, patterns
├── brand-sheets/         Printable HTML reference sheets
├── scripts/              Token build pipeline (Style Dictionary)
├── .github/              Issue/PR templates, workflows, CODEOWNERS
├── CHANGELOG.md          Versioned history of changes
├── CONTRIBUTING.md       How to propose changes
└── LICENSE               Proprietary — Carraro Group / mir-ai.it
```

## Quick links

| You are a… | Start here |
|---|---|
| 🧑‍🎨 **Designer** | [`docs/for-designers.md`](./docs/for-designers.md) → [`design-tokens/figma/IMPORT.md`](./design-tokens/figma/IMPORT.md) |
| 🧑‍💻 **Engineer**  | [`docs/for-engineers.md`](./docs/for-engineers.md) → [`design-tokens/README.md`](./design-tokens/README.md) |
| ✍️ **Copywriter / PM** | [`docs/brand/voice-and-tone.md`](./docs/brand/voice-and-tone.md) |
| 🛡️ **Security / Compliance** | [`docs/brand/compliance-patterns.md`](./docs/brand/compliance-patterns.md) |
| 📜 **Brand guidelines (full)** | [`docs/brand/guidelines.md`](./docs/brand/guidelines.md) |
| 🖼️ **Visual reference sheet** | [`brand-sheets/Ask Brand Sheet.html`](./brand-sheets/Ask%20Brand%20Sheet.html) |
| 🧩 **Component reference**     | [`brand-sheets/Ask Design System.html`](./brand-sheets/Ask%20Design%20System.html) |

## The brand in one paragraph

**ASK is the cognitive infrastructure focused on security and compliance.** It acts as the dashboard, transmission, and braking system that safely harnesses raw AI horsepower to deliver predictable, compliant, and highly secure corporate outcomes. The core essence is **Power Under Control** — compliance reframed from a bureaucratic barrier into an enabling platform for growth.

Three brand pillars carry every design decision:

1. **The Walled Garden** — trust and sovereignty. Zero-trust tenant isolation, GDPR + EU AI Act compliant by construction.
2. **The RAG Engine** — contextual truth. Every output is mathematically bound to verified corporate files. No "Oracle Illusion".
3. **Policy as Code** — invisible governance. Compliance lives in the architecture, not in a PDF.

Read the full positioning in [`docs/brand/guidelines.md`](./docs/brand/guidelines.md).

## Getting started

### Designers

```bash
# 1. Pull the repo (read access is enough)
git clone git@github.com:mirai-srl/project-ask-design-system.git

# 2. Open the brand sheets in your browser for the visual ramp
open "brand-sheets/Ask Brand Sheet.html"
open "brand-sheets/Ask Design System.html"

# 3. Import design tokens into Figma via Tokens Studio
# Follow design-tokens/figma/IMPORT.md
```

### Engineers (shadcn / Next.js / Vite)

```bash
# 1. Add this repo as a git submodule or copy design-tokens/ into your app
cp -R design-tokens/shadcn/globals.css         app/globals.css
cp    design-tokens/shadcn/tailwind.preset.ts  config/

# 2. Reference the preset
#    tailwind.config.ts
#    import askPreset from './config/tailwind.preset'
#    export default { presets: [askPreset], content: [...] }

# 3. Install fonts (Archivo, Archivo Black, JetBrains Mono) — already imported
#    via @import in globals.css. Self-host for production.
```

Full per-tool walk-through: [`design-tokens/README.md`](./design-tokens/README.md).

### Token build pipeline

```bash
# Install dev tooling
pnpm install

# Validate that downstream artifacts are in sync with tokens.json
pnpm run tokens:check

# Regenerate globals.css / tailwind.preset.ts / theme.ts from tokens.json
pnpm run tokens:build
```

`scripts/build-tokens.mjs` runs Style Dictionary against `design-tokens/tokens.json` and writes back into the shadcn/ and storybook/ folders. CI (`tokens-build.yml`) runs `tokens:check` on every PR and fails if you've hand-edited a derived artifact without updating the source.

## Versioning policy

`tokens.json` carries the canonical version of this repo. Semver applies:

| Bump | When | Action required downstream |
|---|---|---|
| **Patch** `1.0.x` | Bug fixes, copy tweaks, doc clarifications | None — pick up at convenience |
| **Minor** `1.x.0` | New tokens, new components, additive only | Designers accept Figma library updates |
| **Major** `x.0.0` | Renames, removals, breaking visual changes | Coordinated migration; communicated in advance |

See [`CHANGELOG.md`](./CHANGELOG.md) for the full history. Tags follow `ask-design@x.y.z`.

## Governance

- **Owner:** Matteo Rizzo · [matteo.rizzo@mir-ai.it](mailto:matteo.rizzo@mir-ai.it)
- **Code owners:** see [`.github/CODEOWNERS`](./.github/CODEOWNERS)
- **Review:** every PR requires owner approval. Token-level changes require a [Token Change Proposal](./.github/ISSUE_TEMPLATE/token_change.yml) first.
- **Status:** **Approved** · **Confidential** · v1.0.0 · last updated 21 May 2026.

## Contributing

Read [`CONTRIBUTING.md`](./CONTRIBUTING.md). The TL;DR:

1. Open an issue using the right template (token / component / pattern / bug).
2. Discuss before you build — design system changes ripple.
3. Branch from `main`, follow Conventional Commits, open a PR.
4. CI must be green and CODEOWNERS must approve.

## License

Proprietary. © Carraro Group / MirAI. All rights reserved. See [`LICENSE`](./LICENSE).