@tarbia/ui — Component Library

Tarbia.io shared UI component library. The single source of visual truth for all Tarbia.io subsystems: TarbiaScale · TarbiLearn · TarbiKids · and all future products.

Package Status

This repository is maintained as a publishable package, not as the completion tracker for every upstream Tarbia brand deliverable.

• Release gates for the package: typecheck, lint, test, build
• Package scope: tokens, styles, theme utilities, React components, Storybook, tests, and npm distribution metadata
• Out of package scope unless separately implemented: missing identity deliverables, logo animation, pattern-system design work, and other audit gaps tracked in IMPLEMENTATION_NOTES.md

Agent Source Of Truth

• Working instructions: CODEX.md, CLAUDE.md, docs/CLAUDE.md
• Canonical brand/system source material: docs/TARBIA_MASTER_COMPLETE.md, docs/brand/TARBIA_BRAND_SYSTEM_01-06.md
• Audit history and gap log: IMPLEMENTATION_NOTES.md

Non-Negotiable Brand Rules

| Rule | Value | |---|---| | Colour plates | Ink · Dust · Ivory · Amber only | | Amber | #C9973A — hardcoded everywhere, never in a switching CSS variable | | Surface | Never #FFFFFF. Use #F7F4EF (Ivory Light) | | Shadows | Zero. Focus ring only: box-shadow: 0 0 0 3px #0891B2 | | Borders | 0.5px solid #2E2A24 always | | Arabic | direction: rtl + text-align: right + line-height: 2.0 minimum | | Urdu | direction: rtl + text-align: right + line-height: 2.6 minimum | | Vocabulary | Five Holistic Dimensions (Moral · Spiritual · Intellectual · Physical · Social) — soul layer terms permanently banned | | Motion | No frivolous animation. Ceiling: 350ms UI · 500ms loading. Always respect prefers-reduced-motion |

Install

# npm
npm install @tarbia/ui

# Turborepo workspace
# In apps/tarbia-scale/package.json:
# "@tarbia/ui": "workspace:*"

Package Boundaries

The package now exposes additive entrypoints so consumers can choose the correct surface explicitly.

| Entrypoint | Intended consumer | Framework requirement | Includes | |---|---|---|---| | @tarbia/ui | Existing Tarbia subsystem apps | Next.js 14+ recommended | Full legacy surface, including Next-coupled layout exports | | @tarbia/ui/core | Generic React UI consumers | React 18 | Tokens, theme, utils, illustrations, forms, feedback, data-display, review, pipeline, marketing | | @tarbia/ui/next | App-shell and routing UI | Next.js 14+ | Layout/navigation components that depend on next/link or next/navigation |

Compatibility Matrix

| Surface | Status | Notes | |---|---|---| | React 18 + Next.js 14+ | Fully supported | Use @tarbia/ui/core plus @tarbia/ui/next, or the legacy root entry | | React 18 without Next.js | Supported for @tarbia/ui/core | Do not import @tarbia/ui root or @tarbia/ui/next | | Root @tarbia/ui in non-Next apps | Not supported | Root still re-exports Next-coupled layout components for backward compatibility | | SSR | Supported on Next.js 14+ | Theme and layout paths are validated against the current Next-oriented subsystem model | | TypeScript 5 | Supported | Package emits .d.ts for root and sub-entrypoints |

Usage

// 1. Import styles once in root layout
import '@tarbia/ui/styles/globals.css'

// 2. Wrap with ThemeProvider
import { ThemeProvider } from '@tarbia/ui/core'
export default function RootLayout({ children }) {
  return <ThemeProvider>{children}</ThemeProvider>
}

// 3. Import generic components from core
import { Button, Badge, Table, Toast } from '@tarbia/ui/core'

// 4. Import Next-coupled layout from the Next entry
import { Sidebar } from '@tarbia/ui/next'

Tree-shaking — granular sub-entry imports

Import only what you need for smaller bundles:

import { Button }      from '@tarbia/ui/components/forms'
import { Badge }       from '@tarbia/ui/components/data-display'
import { Toast }       from '@tarbia/ui/components/feedback'
import { Sidebar }     from '@tarbia/ui/components/layout'
import { ReviewCard }  from '@tarbia/ui/components/review'
import { COLOURS }     from '@tarbia/ui/tokens'
import { rtlStyle }    from '@tarbia/ui/utils'
import { ThemeProvider } from '@tarbia/ui/theme'

Root import policy

• Prefer @tarbia/ui/core for new generic React code.
• Prefer @tarbia/ui/next for layout, navigation, and route-aware components.
• Keep @tarbia/ui only for existing Next-based subsystem code that still expects the full legacy barrel.

Tailwind preset

Extend your project's Tailwind config with the full Tarbia token set:

// tailwind.config.js
module.exports = {
  presets: [require('@tarbia/ui/tailwind')],
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@tarbia/ui/src/**/*.{ts,tsx}',
  ],
}

Development Scripts

npm run build          # build to dist/
npm run dev            # build in watch mode
npm run typecheck      # TypeScript check (no emit)
npm run lint           # ESLint (0 warnings allowed)
npm run lint:fix       # auto-fix lint issues
npm run format         # Prettier format
npm run format:check   # Prettier check (for CI)
npm run test           # run all tests
npm run test:coverage  # run tests + coverage report
npm run test:a11y      # run automated axe checks across exported surfaces
npm run test:cli       # verify the maintainer CLI contract
npm run check:bundle-budgets # enforce dist size budgets
npm run check:chromatic-config # verify CHROMATIC_PROJECT_TOKEN is present
npm run check:storybook-coverage # ensure exported visual modules have stories
npm run cli -- help    # maintainer CLI entrypoint
npm run release:verify # full release gate bundle
npm run release:canary:prepare # snapshot versioning for canary publish
npm run release:version # apply changesets to package/changelog state
npm run release:publish # verify and publish via changesets
npm run release:manifest:sync # sync machine-readable release contract
npm run check:release-manifest # verify release manifest drift
npm run storybook      # start Storybook at localhost:6006
npm run build-storybook # build static Storybook
npm run build-storybook:ci # non-interactive Storybook build for CI
npm run smoke:consumers # packaged consumer smoke checks for React core + Next
npm run check:changeset-required # PR gate for public runtime changes

Quality Gates

Before publishing or tagging a release, the package must pass:

npm run typecheck
npm run lint
npm run test
npm run build

Phase 1 infrastructure also expects:

npm run test:a11y
npm run check:bundle-budgets
npm run check:storybook-coverage
npm run build-storybook:ci
npm run smoke:consumers

Visual regression publishing is wired through .github/workflows/visual-regression.yml and becomes active once CHROMATIC_PROJECT_TOKEN is configured in GitHub Actions.

Release preparation uses:

npm run release:verify

Maintainer CLI

The repo now includes a lightweight maintainer CLI for governance and operational checks:

npm run cli -- help
npm run cli -- doctor --dry-run
npm run cli -- release-ready --base-ref main
npm run cli -- tokens
npm run cli -- tokens --check
npm run cli -- tokens --sync
npm run tokens:figma
npm run check:tokens:figma
npm run parity:sync
npm run check:design-parity
npm run code-connect:sync
npm run check:code-connect
npm run ai:sync
npm run ai:package:sync
npm run release:manifest:sync
npm run check:ai-manifest
npm run check:ai-package
npm run check:release-manifest
npm run cli -- ai-manifest --check
npm run cli -- ai-skill
npm run cli -- release-status
npm run cli -- changeset-required --base-ref main
npm run cli -- chromatic-config

Command surface:

• doctor: runs core repo health checks, including generated token runtime drift detection and design parity registry checks; use --full to include axe and Storybook build checks
• release-ready: runs release:verify and then optional changeset/chromatic checks
• release-status: prints the current version, publish workflows, and client install commands
• ai-skill: prints the packaged first-read AI implementation skill summary
• tokens: prints canonical token inventory, checks generated token runtime drift, or regenerates the runtime token files
• ai-manifest: checks or regenerates the AI surface manifest plus the packaged AI registry modules used by Codex and Claude
• changeset-required: runs the PR-time public runtime changeset policy
• chromatic-config: verifies CHROMATIC_PROJECT_TOKEN presence

AI-First Usage

This package now includes an AI-targeted implementation layer for Codex and Claude:

• packaged first-read contract: AGENTS.md
• universal agent contract: AI_CODING_AGENTS.md
• binding skill file: docs/ai/AI_IMPLEMENTATION_SKILL.md
• agent contract: docs/ai/AI_USAGE_CONTRACT.md
• machine-readable implementation skill: docs/ai/agent-implementation-skill.json
• generated AI surface manifest: docs/ai/agent-surface-manifest.json
• component choice guide: docs/ai/component-selection-guide.md
• subsystem recipes: docs/ai/recipes/
• golden page specs: docs/ai/golden-pages/
• prompt packs: docs/ai/prompts/

Installed client repos can import the machine-readable registries directly:

import { agentImplementationSkill } from '@tarbia/ui/ai/skill'
import { agentSurfaceManifest } from '@tarbia/ui/ai/manifest'
import { designParityRegistry } from '@tarbia/ui/ai/design-parity'
import { codeConnectInventory } from '@tarbia/ui/ai/code-connect'

Required first-read sequence for client-repo agents:

1. node_modules/@tarbia/ui/AGENTS.md
2. node_modules/@tarbia/ui/AI_CODING_AGENTS.md
3. node_modules/@tarbia/ui/docs/ai/AI_IMPLEMENTATION_SKILL.md
4. @tarbia/ui/ai/skill
5. @tarbia/ui/ai/manifest

Use these exports to drive agent import policy, approved component choice, and design/code traceability in Tarbia subsystem repos.

Design System Roadmap

• Execution roadmap: coding-agents-plan/2026-04-07-design-system-maturity-roadmap.md
• AI-first implementation plan: coding-agents-plan/2026-04-08-ai-first-library-implementation-plan.md
• Package boundaries: docs/architecture/package-boundaries.md
• Token source policy: docs/architecture/token-governance.md
• Design parity rules: docs/architecture/design-parity.md
• Code Connect preparation: docs/architecture/code-connect.md
• Compatibility matrix: docs/compatibility-matrix.md
• Accessibility program skeleton: docs/accessibility/README.md
• Release governance skeleton: docs/releases/README.md
• Chromatic activation guide: docs/releases/chromatic-setup.md
• Accessibility workstation runbook: docs/accessibility/workstation-runbook.md

Contributing — changeset workflow

# 1. Make your changes
# 2. Create a changeset describing them
npm run changeset    # select major/minor/patch + write description

# 3. Keep the release manifest in sync when package metadata changes
npm run release:manifest:sync

# 4. If your PR changes the public runtime surface, commit a .changeset/ file with it
git add . && git commit -m "feat: your change"

# Stable release flow (maintainer only):
# - merge approved changesets to main
# - .github/workflows/release.yml opens/updates the release PR
# - merging the release PR publishes @tarbia/ui with the latest tag

# Fallback/manual flow:
npm run release:verify
npm run release:version
git tag v1.x.x
git push --tags

Additional governance material:

• docs/releases/release-checklist.md
• docs/releases/canary-policy.md
• docs/releases/rollback-runbook.md
• docs/releases/deprecation-policy.md
• docs/releases/migration-template.md
• docs/releases/versioning-policy.md
• docs/releases/client-upgrade-policy.md
• docs/releases/release-manifest.json
• docs/releases/dependabot-tarbia-ui-template.yml

Repository Structure

tarbia-ui/
├── CLAUDE.md                          ← Non-negotiable rules for Claude Code sessions
├── README.md                          ← This file
├── IMPLEMENTATION_NOTES.md            ← Full audit log, gap analysis, pending items
├── package.json                       ← @tarbia/ui · dual ESM/CJS exports
├── tsconfig.json                      ← TypeScript config (ES2020, strict, bundler)
├── tsconfig.build.json                ← Build-specific TS config (outDir, rootDir)
├── tailwind.config.js                 ← Brand tokens mapped to Tailwind classes (6.9KB)
├── postcss.config.js                  ← tailwindcss + autoprefixer
├── .gitignore
├── .npmrc                             ← Scope registry + exact versioning
│
├── src/
│   ├── index.ts                       ← Root barrel: exports all tokens, utils, theme, components
│   │
│   ├── tokens/                        ← Design tokens — the single colour source of truth
│   │   ├── colours.ts                 ← COLOURS const: all hex values, 4 plates + functional strip
│   │   ├── colour-tokens.ts           ← Semantic CSS vars mapped per mode (dark + light)
│   │   ├── spacing.ts                 ← 4px base unit scale (0→96px)
│   │   ├── radius.ts                  ← Locked values: sm(6) · md(8) · lg(12) · pill(20) · none
│   │   ├── shadow.ts                  ← Zero shadows — focus ring only: 0 0 0 3px #0891B2
│   │   ├── typography.ts              ← 4 fonts · 3 scripts · RTL line-heights baked in
│   │   ├── motion.ts                  ← Easing curves · duration ceiling 350ms/500ms
│   │   └── index.ts                   ← Barrel export
│   │
│   ├── styles/                        ← Global CSS (no React deps — import once at root)
│   │   ├── globals.css                ← Font loading · all --color-* tokens · base classes (22KB)
│   │   ├── micro-interactions.css     ← Button press · badge appear · sidebar expand (7.5KB)
│   │   └── patterns.css              ← Pattern scaffold retained for future identity work
│   │
│   ├── types/                         ← Shared TypeScript types
│   │   ├── common.ts                  ← Direction · Script · Size · Variant · Status · BaseProps · RTLProps
│   │   ├── theme.ts                   ← ThemeMode ('dark'|'light') · ThemeContextValue
│   │   └── index.ts
│   │
│   ├── utils/                         ← Pure utility functions
│   │   ├── cn.ts                      ← Class name merge — Tailwind conflict-safe
│   │   ├── rtl.ts                     ← getScriptDirection · getScriptLineHeight · rtlStyle()
│   │   └── index.ts
│   │
│   ├── theme/                         ← Dark/light mode system (Next.js implementation)
│   │   ├── ThemeProvider.tsx          ← Context provider · toggles .dark class on <html>
│   │   ├── ThemeToggle.tsx            ← UI toggle button component
│   │   ├── prevent-fouc.ts            ← Inline script to prevent flash-of-unstyled-content
│   │   ├── layout.example.tsx         ← How to integrate into Next.js root layout
│   │   ├── usage.example.tsx          ← Basic usage example
│   │   └── index.ts
│   │
│   ├── illustrations/                 ← Standalone visual components (no component deps)
│   │   ├── Icons.tsx                  ← Icon system: consistent stroke, amber accents, RTL variants (10.9KB)
│   │   ├── Illustrations.tsx          ← Empty state + branded illustrations (10.2KB)
│   │   ├── DataViz.tsx                ← Chart components: teal/amber/cyan palette (12.2KB)
│   │   └── index.ts
│   │
│   └── components/
│       │
│       ├── layout/                    ← App shell · Phase 12 (most complex — depends on Icons, Button, Badge)
│       │   ├── Sidebar.tsx            ← Full sidebar: wordmark · section labels · nav · active/hover (12.4KB)
│       │   ├── SidebarCollapsed.tsx   ← Icon-only view · tooltip on hover · toggle (15.9KB)
│       │   ├── TopBar.tsx             ← Header: user pill · admin badge · dark toggle · sign out (4.2KB)
│       │   ├── MobileNav.tsx          ← Drawer nav · branded · RTL-aware Arabic/Urdu (15.8KB)
│       │   ├── TabBar.tsx             ← Horizontal tabs · amber underline active · both modes (2.8KB)
│       │   ├── Breadcrumb.tsx         ← Page wayfinding · amber current · muted separators
│       │   ├── PageTransition.tsx     ← Route change animation · subtle · max 350ms (3.7KB)
│       │   └── index.ts
│       │
│       ├── forms/                     ← Input components · Phase 7 (Button built first — no deps)
│       │   ├── Button.tsx             ← Primary(amber) · Secondary · Destructive(rose) · Ghost · Icon-only (8KB)
│       │   ├── Input.tsx              ← Default · focus(cyan ring) · error(rose) · disabled · both modes (7.7KB)
│       │   ├── Select.tsx             ← Amber chevron · option list · hover states (8KB)
│       │   ├── CheckboxRadio.tsx      ← Amber checked state · custom mark · both modes (8KB)
│       │   ├── Toggle.tsx             ← On(teal) · Off(dust) · for settings + dark mode (5.8KB)
│       │   ├── SearchInput.tsx        ← Amber icon · clear button · focus ring (6.1KB)
│       │   ├── FileUpload.tsx         ← Drag-drop zone · progress · file type indicators (11.5KB)
│       │   └── index.ts
│       │
│       ├── feedback/                  ← Notifications and overlays · Phase 8 (depends on Button)
│       │   ├── Toast.tsx              ← Success(teal) · Error(rose) · Info(cyan) · Warning(rose) (9.4KB)
│       │   ├── Alert.tsx              ← Inline callout banners · 4 semantic variants (6.4KB)
│       │   ├── Modal.tsx              ← role="dialog" · aria-modal · both modes (9.9KB)
│       │   ├── Tooltip.tsx            ← Ink Dark bg · warm off-white text · arrow pointer (5KB)
│       │   ├── Loading.tsx            ← Skeleton loaders · Spinner(amber) · progress (7.9KB)
│       │   ├── SkeletonAnimation.tsx  ← Shimmer: amber direction · branded pulse not gray (11.2KB)
│       │   └── index.ts
│       │
│       ├── data-display/              ← Data presentation · Phase 9 (depends on Icons)
│       │   ├── Badge.tsx              ← 10 states: complete · approved · failed · pending · reviewing · tagging · processing · chunking · queued · embedding (4.6KB)
│       │   ├── Table.tsx              ← Header · rows · hover · sorting · empty state · both modes (9.8KB)
│       │   ├── StatCard.tsx           ← Dashboard metric cards: Total Jobs · Completed · Failed · Pending (7.1KB)
│       │   ├── ProgressBar.tsx        ← Teal fill · amber accent · aria-progressbar
│       │   ├── EmptyState.tsx         ← No data · no results · no documents (9.9KB)
│       │   ├── Pagination.tsx         ← Page numbers · prev/next · amber active (7.9KB)
│       │   └── index.ts
│       │
│       ├── review/                    ← Review Queue UI · Phase 10 (depends on Badge, Button)
│       │   ├── ReviewFilters.tsx      ← LANG & STAGE filter pills · amber active · ivory inactive (8.6KB)
│       │   ├── ReviewCard.tsx         ← Trilingual card: UthmanicHafs Arabic + Jameel Noori Urdu + Latin
│       │   ├── ReviewActions.tsx      ← Approve · Reject · Send Back · History (12.2KB)
│       │   ├── PendingCount.tsx       ← 8,130 pending · amber number · muted label (5.6KB)
│       │   └── index.ts
│       │
│       ├── pipeline/                  ← Export & Pipeline UI · Phase 11 (depends on Badge, Button)
│       │   ├── ExportCards.tsx        ← Approved final · Classified · Unclassified stat cards (7KB)
│       │   ├── ExportRunsTable.tsx    ← Run ID(mono) · Artifacts · Records · Created · Download (10.8KB)
│       │   ├── ExportActions.tsx      ← Connect Drive · Download · Generate Export hierarchy (7.6KB)
│       │   ├── HealthDashboard.tsx    ← System health indicators · pipeline status · monitoring (10.2KB)
│       │   └── index.ts
│       │
│       ├── marketing/                 ← Digital marketing components · Phase 13
│       │   ├── ContentCards.tsx       ← TarbiModule cards · knowledge tiles · research cards (13.3KB)
│       │   ├── EmailTemplate.tsx      ← Transactional email · amber CTA · LTR + RTL (12.9KB)
│       │   └── index.ts
│       │
│       └── index.ts                   ← Master barrel: re-exports all 7 component groups
│
├── assets/                            ← Static brand assets (not processed by bundler)
│   ├── logos/                         ← 10 SVG logo variants
│   │   ├── tarbia-logomark-dark.svg
│   │   ├── tarbia-logomark-light.svg
│   │   ├── tarbia-logomark-transparent.svg
│   │   ├── tarbia-logomark-mono-black.svg
│   │   ├── tarbia-logomark-mono-white.svg
│   │   ├── tarbia-logomark-teal.svg
│   │   ├── tarbia-lockup-dark.svg         ← Horizontal wordmark + icon lockup
│   │   ├── tarbiascale-lockup-dark.svg
│   │   ├── tarbiascale-lockup-light.svg
│   │   └── tarbiascale-lockup-stacked-dark.svg
│   │
│   ├── favicons/                      ← Browser and PWA icons
│   │   ├── favicon-16.svg
│   │   ├── favicon-32.svg
│   │   ├── favicon-180.svg            ← Apple touch icon
│   │   ├── favicon-512.svg            ← PWA icon
│   │   └── manifest.json              ← Web app manifest
│   │
│   ├── og/                            ← Open Graph social card templates
│   │   ├── og-card-dark.svg           ← 1200×630 dark variant
│   │   └── og-card-light.svg          ← 1200×630 light variant
│   │
│   ├── print/                         ← Print and physical collateral
│   │   ├── business-card.svg          ← Ink dark bg · amber accent · bilingual
│   │   ├── business-card-spec.md      ← Dimensions and print specifications
│   │   ├── letterhead.svg             ← Institutional letterhead
│   │   ├── poster-system.svg          ← Conference/event poster template
│   │   └── TARBIA_PRESENTATION_TEMPLATE.pptx  ← PowerPoint master (title · content · divider slides)
│   │
│   └── images/                        ← Brand reference photography
│       ├── Tarbia logo icon 1.jpeg
│       └── WhatsApp Image 2026-04-06 at 17.53.32.jpeg
│
├── docs/                              ← Full brand system documentation
│   ├── CLAUDE.md                      ← Rules copy for AI sessions
│   ├── CLAUDE_CODE_PROMPT.md          ← Full Claude Code scaffold prompt (16.8KB)
│   ├── TARBIA_MASTER_COMPLETE.md      ← MASTER REFERENCE: 5869 lines · complete brand system (183KB)
│   ├── TARBIA_BRAND_GUIDELINES.pdf    ← Shareable brand guidelines PDF
│   ├── TARBIA_UI_REPO_STRUCTURE.md    ← Repo structure reference (196 lines)
│   ├── Tarbia_Brand_System_Lock_v1.docx  ← Human-readable Word lock document
│   │
│   ├── brand/                         ← Foundations documentation (categories 01–06 master)
│   │   ├── TARBIA_BRAND_SYSTEM_01-06.md   ← MASTER for cats 01–06: 2279 lines · 70KB
│   │   │                                    (brand philosophy · colour system · typography ·
│   │   │                                     type scale · decision log · CSS · navigation ·
│   │   │                                     data display · review queue)
│   │   ├── TARBIA_BRAND_SYSTEM_MASTER_v12.docx  ← Word version of master
│   │   ├── v2.pdf                     ← Brand visual reference PDF (6.8MB — colour plates, type specimens)
│   │   ├── 01-brand-philosophy.md     ← Mission · 5 design principles · brand hierarchy
│   │   ├── 01-colour-system.md        ← 4 families + functional strip
│   │   ├── 01-colour-tokens.md        ← All --color-* semantic tokens · both modes
│   │   ├── 01-typography.md           ← 4 fonts · 3 scripts
│   │   ├── 01-type-scale.md           ← 10px–28px Latin · 13px–26px Urdu
│   │   ├── 01-decision-log.md         ← D-001 to D-009 brand decisions
│   │   ├── 01-messaging-framework.md  ← PENDING (new gap)
│   │   ├── 01-grid-spacing.md         ← PENDING (new gap)
│   │   ├── 01-border-radius.md        ← PENDING (new gap)
│   │   └── 01-shadow-elevation.md     ← PENDING (new gap)
│   │
│   ├── identity/                      ← Brand identity docs (category 02)
│   │   ├── 02-favicon-guide.md        ← Favicon implementation guide
│   │   ├── 02-logo-rules.md           ← PENDING (new gap)
│   │   ├── 02-logo-animation.md       ← PENDING (new gap)
│   │   └── 02-pattern-system.md       ← PENDING (new gap — Islamic geometric patterns)
│   │
│   ├── components/                    ← Per-category component specifications
│   │   ├── 04-navigation.md           ← → see brand/TARBIA_BRAND_SYSTEM_01-06.md
│   │   ├── 05-data-display.md         ← → see brand/TARBIA_BRAND_SYSTEM_01-06.md
│   │   ├── 06-review-queue.md         ← → see brand/TARBIA_BRAND_SYSTEM_01-06.md
│   │   ├── 07-form-elements.md        ← Full spec: 1890 lines · 61KB
│   │   ├── 08-feedback-notifications.md  ← Full spec: 1437 lines · 46KB
│   │   ├── 09-export-pipeline-ui.md   ← Full spec: 1354 lines · 43KB
│   │   ├── 10-illustration-language.md   ← Full spec: 1289 lines · 45KB
│   │   ├── 11-motion-interaction.md   ← Full spec: 1081 lines · 33KB
│   │   ├── 12-print-physical.md       ← Full spec: 156 lines · 5.6KB
│   │   ├── 13-digital-marketing.md    ← Full spec: 1123 lines · 41KB
│   │   └── 14-documentation.md        ← Documentation category spec
│   │
│   └── guides/                        ← Implementation guides for developers
│       ├── component-usage-guide.md   ← DO/DON'T for every component (424 lines · 11.8KB)
│       ├── rtl-implementation-guide.md   ← Arabic/Urdu layout rules for Next.js (383 lines · 9.7KB)
│       ├── accessibility-checklist.md ← WCAG 2.1 AA full checklist (289 lines · 9.5KB)
│       ├── animation-principles.md    ← Motion rules · easing · Islamic principle (130 lines)
│       ├── imagery-direction.md       ← Photography + AI visual rules (165 lines · 6KB)
│       ├── illustration-style-guide.md  ← Soul-layer metaphors · geometric motifs (145 lines)
│       └── business-card-spec.md      ← Print specs for business card (40 lines)
│
└── _unplaced/                         ← Source files with no designated location in spec
    ├── CHECK LIST Tarbia Brand Kit.docx   ← Brand kit progress checklist (20.6KB)
    ├── Tarbia Brand Kit — Complete Checklist v2.zip
    └── brand-history/                 ← Superseded brand system versions — kept for reference
        ├── TARBIA_BRAND_SYSTEM.md     ← v1 original
        ├── TARBIA_BRAND_SYSTEM (1).md ← v1 duplicate
        ├── TARBIA_BRAND_SYSTEM 4.md   ← v4
        ├── TARBIA_BRAND_SYSTEM 5.md   ← v5
        ├── TARBIA_BRAND_SYSTEM 6.md   ← v6
        └── TARBIA_BRAND_SYSTEM v2.md  ← v2
        (Current canonical version: docs/brand/TARBIA_BRAND_SYSTEM_01-06.md)

Token Architecture

All colour values live in exactly one place. Nothing else contains a raw hex value.

tokens/canonical/*.json         ← canonical token source of truth
        ↓
scripts/sync-token-runtime.mjs  ← generates runtime token modules from canonical JSON
        ↓
src/tokens/colours.ts           ← generated foundational token runtime
        ↓
src/tokens/colour-tokens.ts     ← generated semantic CSS vars per mode (dark / light)
        ↓
scripts/export-figma-tokens.mjs ← generates export-ready Figma token artifact
        ↓
tokens/figma/tokens.json        ← generated DTCG-like Figma export
        ↓
src/styles/globals.css           ← :root { } and .dark { } CSS custom properties
        ↓
All components                   ← reference var(--color-*) or COLOURS.*

Verification commands:

npm run tokens:sync
npm run check:tokens
npm run tokens:figma
npm run check:tokens:figma
npm run cli -- tokens --check

Amber rule: #C9973A is always hardcoded. Never inside a switching CSS variable. This is enforced by CLAUDE.md rule 2 and verified by the grep check below.

Build Phases (strict dependency order)

| Phase | What | Depends on | |---|---|---| | 1 | Root config files | — | | 2 | src/tokens/ | — | | 3 | src/styles/ | tokens | | 4 | src/utils/ | types | | 5 | src/theme/ | types | | 6 | src/illustrations/ | — | | 7 | src/components/forms/ | Button first, no other deps | | 8 | src/components/feedback/ | Button | | 9 | src/components/data-display/ | Icons | | 10 | src/components/review/ | Badge, Button | | 11 | src/components/pipeline/ | Badge, Button | | 12 | src/components/layout/ | Icons + Button + Badge (most complex) | | 13 | src/components/marketing/ | — | | 14 | Barrel index.ts files | all of the above | | 15 | README.md, CLAUDE.md | — |

Verification Commands

Run after every change to enforce brand compliance:

# TypeScript — must be zero errors
npx tsc --noEmit

# Amber must never be inside a switching CSS variable
grep -r "C9973A" src/styles/ | grep "var(--" && echo "VIOLATION" || echo "OK"

# No #FFFFFF surface anywhere in components
grep -r "#ffffff\|#FFFFFF\|#fff\b" src/components/ && echo "VIOLATION" || echo "OK"

# No shadows except the focus ring
grep -rn "box-shadow" src/components/ | grep -v "0891B2" && echo "VIOLATION" || echo "OK"

# Arabic/Urdu line-height never below minimum
grep -rn "lineHeight.*1\.[0-9]" src/ | grep -i "ar\|arabic\|urdu\|rtl" && echo "RTL VIOLATION" || echo "OK"

Colour Plates Quick Reference

| Plate | Tokens | Usage | |---|---|---| | Ink | #131210 #1C1A17 #2E2A24 | Dark mode surfaces, borders | | Dust | #5A5248 #9A8C7A #C4B8A8 | Muted text, disabled states | | Ivory | #E2DDD4 #F0EBE3 #F7F4EF | Light mode surfaces | | Amber | #C9973A #9A6C1F #FAE4A8 | Primary accent — never changes between modes | | Teal | #1D8C7E | Success, active pipeline, toggle on | | Cyan | #0891B2 | Focus ring, info states | | Rose | #C0544A | Destructive, error states |

Audit & Gap Status

IMPLEMENTATION_NOTES.md is an audit log for the wider Tarbia brand-system recovery effort. It is useful context, but it is not the package release contract.

• Package release contract: passing quality gates and correct published exports
• Audit-only backlog: missing upstream identity/pattern/logo deliverables and other non-package source gaps
• Generated-from-spec components that are intentionally shipped in this package: ProgressBar, ReviewCard, Breadcrumb

Full audit log: IMPLEMENTATION_NOTES.md