# MirAI Design System > **AI Governance. Human Vision.** This repository is the canonical design system for **MirAI**, an enterprise AI infrastructure company, and its flagship orchestration platform **ASK**. The system is engineered to be far more than a component library — it is a mechanism of *cognitive scaffolding* that codifies the corporate manifesto into visual, interactive, and linguistic form. → **[Open `index.html`](./index.html)** for the visual repo overview. → **[Open `tokens/`](./tokens)** for design tokens (W3C DTCG, Tokens Studio, shadcn, Tailwind). → **[Open `preview/brand-sheet.html`](./preview/brand-sheet.html)** for the one-page identity overview. --- ## 0. Quickstart ### Consume the tokens ```bash # shadcn / Tailwind project cp -r tokens ./src/styles/mirai # then in your globals.css: @import "./src/styles/mirai/shadcn.css"; # then in your tailwind.config.js: presets: [require("./src/styles/mirai/tailwind.preset")] ``` ```bash # Style Dictionary — compile to CSS / SCSS / JS / iOS / Android npm i -D style-dictionary npx style-dictionary build --config tokens/style-dictionary.config.js ``` ```text # Figma (Tokens Studio plugin) Plugins → Tokens Studio → Tools → Import → Single file → select tokens/figma.tokens.json ``` ### Run Storybook locally ```bash npm install npm run storybook # → http://localhost:6006 npm run build-storybook # → storybook-static/ ``` Stories are organized as **Introduction → Foundations → Components → Patterns**. Foundations are MDX, components are `.stories.tsx`. See [`stories/README.md`](./stories/README.md) for conventions. --- ## 1. Company & product context **MirAI** is an enterprise AI infrastructure company. Its mission is to orchestrate the secure transition from unstructured, risky use of generative AI to *engineered governance*. MirAI sits as the middleware layer between raw LLM compute and daily business workflows. **ASK** is the flagship product — a four-tier orchestration platform: | Tier | Component | Role | |------|-----------|------| | L3 — Logic | User Interaction Containers | The presentation layer the user touches: General Chat, Research Notebook, Vertical Apps | | L2 — Workflow | Intent Orchestration Engine | Routes queries, picks tools, coordinates execution | | L1 — Engine | Independent Execution Tools | Semantic search, code sandboxes, MCP connectors | | L0 — Control | Infrastructure Guardrails | Identity, PII filtering, audit logs | The platform addresses three pathologies: - **Shadow AI** — unauthorized use of consumer AI tools. ASK counters this with a *Walled Garden* tenant. - **Cognitive Spillover** — accepting AI hallucinations as fact. ASK enforces *Retrieval-Augmented Generation* with mandatory inline citations. - **Cognitive Debt** — degraded thinking from unstructured AI use. ASK provides *App Verticals* — guided workflows that replace the blank prompt. The three user environments are **General Chat**, **Research Notebook** (split-pane chat + workbench), and **Vertical Apps** (transactional, step-by-step, write-capable with HITL approval). ### Sources All material in this system was derived from a single source of truth provided by MirAI: - `uploads/MirAI - Guidelines - Design System.pdf` — 22-page design system specification (authored by Matteo Rizzo, MirAI). Status: Approved. Visibility: Confidential. - `uploads/MirAI Logo.svg`, `MirAI Icon.svg`, `MirAI Icon Squared.svg` and PNG variants — official brand marks. No codebase or Figma file was attached. The visual recreations in `ui_kits/` are pixel-faithful interpretations of the architectural and component prescriptions in the PDF — not screenshots of a shipping product. **If a real ASK codebase or Figma exists, please attach it** so this kit can be cross-referenced. --- ## 2. Content fundamentals — Tone of Voice The MirAI tone of voice is **assertive when constraining, empathetic when guiding** — a deliberate dichotomy that mirrors the visual one. Voice is treated as a design token; its register shifts with context. | Context | Tone | Example copy | |---|---|---| | Constraints / guardrails | Assertive, authoritative | *"Access restricted. This application is mathematically bound to the Legal Knowledge Pod."* | | Data retrieval / processing | Objective, analytical | *"Aggregating sources. Cross-referencing current SharePoint directories against user ACLs."* | | Errors / recovery | Empathetic, resourceful | *"Source document unavailable. Consider expanding the search parameters or verifying your departmental credentials."* | | Success / completion | Concise, professional | *"Task executed. Audit log securely updated. Output artifacts saved to workbench."* | ### Writing rules - **Sentence case for UI**, including buttons (`Run query`, not `Run Query`). Reserve **Title Case** for product nouns: *Walled Garden*, *Research Notebook*, *Vertical Apps*, *Knowledge Pod*, *Shadow AI Radar*. - **Address the user as "you"** for actions; reference the system as **"the platform"** or by its proper noun (*ASK*, *MirAI*). Avoid "I" or "we" anywhere outside marketing copy. - **No emoji.** Anywhere. Ever. Emoji are visual noise that contradicts the brutalist clarity of the system. - **No marketing exclamations.** No "🎉", no "Awesome!", no "Let's go!". The platform never celebrates; it confirms. - **Use the platform's vocabulary literally.** Pods, Groups, ACLs, RAG, MCP connectors, App Verticals, Audit Trail, HITL checkpoint, Walled Garden, Shadow AI. Don't soften technical terms — the audience is enterprise IT and security. - **State, don't suggest.** "Run query" not "Want to run a query?" "Action requires approval." not "It looks like this might need approval." - **Numbers are facts.** Always render with tabular figures. Always include the unit. Always include the timestamp on audit lines. ### Vibe Cold institutional precision, softened by occasional humanistic phrasing. Reads like a piece of regulatory infrastructure that quietly respects you. Closer to *Palantir Foundry* or *Stripe Atlas* documentation than *Notion* or *Linear*. Never folksy. Never breezy. --- ## 3. Visual foundations ### Color — the Tri-Color Restrictive Palette The system has **exactly three primary values**. Do not introduce new hues. Do not introduce new gray hex codes. All grays are derived as alpha channels of pure black. | Token | Value | Use | |---|---|---| | **Pure White** | `#FFFFFF` | Primary backgrounds, active card surfaces, type on dark | | **Pure Black** | `#000000` | Primary headings, structural borders, high-contrast active states | | **MirAI Blue** | `#556DD7` | Primary CTAs, healthy system status, governed data, the "Human Vision" accent | | `--text-secondary` | `rgba(0,0,0,0.65)` | Body copy, metadata, timestamps | | `--border-subtle` | `rgba(0,0,0,0.15)` | 1px brutalist grid lines | | `--surface-muted` | `rgba(0,0,0,0.04)` | Table headers, hovered rows | **Accessibility.** `#000` on `#FFF` is 21:1 — past AAA. Pure black is reserved for headings, data points, and nav so prolonged-reading fatigue is avoided; bulk body copy uses the 65% alpha token, which clears WCAG AA at 4.5:1. `#556DD7` passes AA against both white and black. ### Typography — Space Grotesk, exclusively Space Grotesk is the *only* typeface in the system. Designed by Florian Karsten in 2018 as a proportional sans-serif derivative of Space Mono. Chosen because: - Its monospace heritage telegraphs *code*, *terminals*, *engineering*. - Its humanistic quirks (the diagonal cut on the lowercase `g`, the expanded oval counters) prevent the interface from feeling dystopic. - Its tabular figures align numerical data perfectly along the Y-axis — enable with `font-variant-numeric: tabular-nums` for any audit log, IP, or financial value. Scale: **Display 48 / H2 32 / H3 24 / H4 20 / Body 18-16 / Meta 14 / Caption 12.** Body line height is 1.5. ### Backgrounds & imagery Backgrounds are **pure white or pure black** — full stop. No gradients, no images, no patterns, no grain, no textures, no decorative SVG. The single exception is the **industrial hazard-tape pattern** (45° black/white stripes) used to flag *Shadow AI* on the Shadow AI Radar — this is a semantic visualization, not decoration. ### Borders & corners — the duality - **Static / structural / data-bearing** elements use **0px or 4px** radii. They are the immutable walls. - **Interactive** elements (buttons, inputs, menus) use **8px** radii. They are the points of human-computer interaction — softened intentionally. - **1px borders** at `--border-subtle` are the dominant structural device. Cards, tables, panels, dividers — everything is bounded by an explicit grid line. ### Shadows **Brutalist hard shadows only.** Solid, unblurred, geometric offset: ```css box-shadow: 4px 4px 0 #000000; ``` **Forbidden:** soft drop shadows, blurred shadows, glassmorphism, neumorphism, backdrop-filter blur. These convey fragility and obfuscation — the opposite of an authoritative security platform. ### Hover & press states - **Primary buttons:** hover applies an **inset shadow** of 10% black overlaid on the blue (`inset 0 0 0 100px rgba(0,0,0,0.1)`). This is tactile, immediate, non-fading. - **Secondary buttons:** hover **fully inverts** — transparent → solid black background, black border, white text. No transition gradient; a deterministic snap. - **Press:** deepen the inset to ~18% black. No scale transforms. No bouncing. - **Links:** underline thickens from `--blue-30` to solid `--mirai-blue`. - **Rows:** hover background goes to `--surface-muted` (`rgba(0,0,0,0.04)`). ### Motion Deterministic. Purposeful. Never decorative. - **Easing:** `cubic-bezier(0.2, 0.8, 0.2, 1)` (sharp ease-out) for everything. No bounce. No elastic. No spring. - **Duration:** 120ms (fast), 180ms (base), 280ms (slow). Anything longer feels uncertain. - **Stagger:** dashboard panels load with a 50ms cascade — the eye is led top-to-bottom through hierarchy. - **Skeletons:** loading uses skeleton placeholders shaped like the eventual content. Never a spinner. Never a progress bar without a percentage. - **Streaming cursor:** a solid 8px MirAI Blue block, pulsing 1Hz with steady opacity (1 → 0.35 → 1). The "heartbeat" of Human Vision inside the machine. ### Transparency & blur `backdrop-filter` is **forbidden**. Translucency suggests obfuscation, which contradicts the platform's promise of transparency. The only allowed alpha use is on Pure Black (for derived gray tokens) and Pure Blue (for focus rings, governed-data fills). ### Layout rules - 4px base spacing scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. - Max content width: 1280px. Density is preferred to whitespace — this is enterprise software. - Nav, headers, sidebars are **fixed**, never floating cards. They are part of the architecture. - Tables and lists use 1px subtle borders between rows; muted-surface table headers; tabular numerics throughout. --- ## 4. Iconography The brand assets included are the MirAI wordmark and the apostrophe icon (a stylized open-quote / close-quote pair in MirAI Blue — symbolizing the platform's role as the "voice" of governed AI). Both ship as SVG and PNG in `assets/`. For UI iconography the brand spec does not name a specific icon set. We've adopted **Lucide** (`lucide.dev`) as the sanctioned UI icon library — its 1.5px stroke weight, geometric construction, and open-source license align with the brutalist aesthetic. Icons are loaded from CDN in the UI kit. **Flag this substitution to the user — if an internal icon set exists, swap it in.** Icon usage rules: - Always 1.5px stroke. Never filled silhouettes. - Render at 16px / 20px / 24px sizes. Match the surrounding text-line height. - Color: `currentColor`. Inherits from text, so blue on primary buttons, black/65% on body. - **Never use emoji** as a substitute for icons. Never use unicode symbols (✓, ✗, →) as decorative glyphs — only as in-text grammar. - Never invent SVG — use Lucide or extend it via the formal contribution model. --- ## 5. Index of files ``` . ├── README.md ← you are here ├── CHANGELOG.md ← versioned change log ├── LICENSE ← confidential, MirAI-internal ├── package.json ← workspace + Storybook scripts ├── index.html ← repo landing / overview page ├── SKILL.md ← Agent Skill manifest (Claude Code) ├── colors_and_type.css ← CSS custom properties + base classes │ ├── tokens/ ← SOURCE OF TRUTH │ ├── README.md │ ├── tokens.json W3C Design Tokens (DTCG) │ ├── figma.tokens.json Tokens Studio for Figma │ ├── shadcn.css CSS vars in HSL (shadcn convention) │ ├── tailwind.preset.js Tailwind theme preset │ └── style-dictionary.config.js multi-platform build config │ ├── assets/ ← brand marks (4 SVG + 4 PNG) │ ├── mirai-logo-light.{svg,png} full wordmark, color │ ├── mirai-logo-white.{svg,png} full wordmark, monochrome │ ├── mirai-icon-light.{svg,png} apostrophe icon, MirAI Blue │ └── mirai-icon-white.{svg,png} apostrophe icon, monochrome │ ├── fonts/ │ └── SpaceGrotesk-VariableFont_wght.ttf │ ├── .storybook/ ← Storybook 8 config │ ├── main.ts │ ├── preview.ts │ └── preview-head.html │ ├── stories/ ← runnable docs │ ├── README.md │ ├── Introduction.mdx │ ├── Foundations/ │ │ ├── Colors.mdx │ │ ├── Typography.mdx │ │ ├── Spacing.mdx │ │ └── Logo.mdx │ └── Components/ │ ├── Button.stories.tsx │ └── Badge.stories.tsx │ ├── preview/ ← static review cards │ ├── brand-sheet.html ★ one-page identity overview │ ├── logo-system.html ★ exportable mark variants │ ├── colors-* · type-* · buttons-* · inputs │ └── radii · shadows · spacing-scale · etc. │ ├── ui_kits/ask/ ← reference React implementation │ ├── README.md │ ├── index.html interactive click-thru prototype │ └── *.jsx │ └── uploads/ ← provenance — DO NOT EDIT ├── MirAI - Guidelines - Design System.pdf └── original brand materials ``` --- ## 6. Caveats & open questions - **No source code or Figma was provided.** The UI kit is built from the architectural prescriptions in the PDF. If a shipping ASK codebase exists, please attach it for pixel-fidelity calibration. - **Icon library substitution.** Lucide is being used as a placeholder. If MirAI has its own icon set, swap. - **Space Grotesk** is loaded from the brand's variable font file at `fonts/SpaceGrotesk-VariableFont_wght.ttf` (weights 300–700).