<!-- GEN:front-matter -->

# Araxxe Pattern Library

<!-- Hand-written prose lives in docs/ai/design-template.md; token values and tables are
injected by scripts/generate-ai-docs.mjs. Edit the template, then run: npm run ai-docs -->

## Overview

The Araxxe design system styles the web applications of Araxxe, a company providing
telecom revenue-assurance and interconnect-fraud-detection services. The applications are
information-dense B2B dashboards: tables, charts, forms and monitoring views.

The visual identity is built on a **gold brand color** (`#b0971c`, lightened `#d6c261`)
over light, warm-grey surfaces (`#f8f7f5` page background), with **Roboto** as the
primary typeface at a compact **14px base size**. Semantic status colors (danger,
warning, valid, at-risk) carry meaning consistently across all products, and each Araxxe
service line (EBV, A2P SMS, SIM-box, CTQ/QoS) has its own accent color used in charts and
service-scoped views.

The single integration surface is CSS: consuming apps load `tikui.css` from the
pattern-library host and compose the documented `araxxe-*` classes. The complete
component usage reference (classes, modifiers, markup examples) lives in the component
catalog: `{DOMAIN}/ai/components-index.md`. This file documents the identity layer:
tokens and the rules for applying them.

## Colors

Gold is reserved for primary actions, active states and brand highlights. Neutral text
and surfaces use the shade ramp (0 = black … 100 = white); body text sits at `shade5` on
`shade100`/`background` surfaces. Status colors are semantic - use them only for their
meaning, never decoratively. Graph colors are a fixed categorical palette for charts;
service colors identify Araxxe product lines.

<!-- GEN:colors-table -->

<!-- GEN:colors-domain-tables -->

## Typography

Roboto (300/400/700, with italics) is the primary typeface for all UI text. Titillium Web
(300/400/600) is the secondary typeface, used sparingly for display/branding accents.
Font sizes are authored in `rem` against the 14px root size; the resolved pixel values
are listed below.

<!-- GEN:typography-table -->

## Layout

Pages are centered at a fixed content width, with a fixed-height application header.
Spacing inside components uses the quark padding steps; there is deliberately no free
per-pixel spacing scale.

<!-- GEN:layout-values -->

## Elevation & Depth

Elevation is minimal: one soft ambient shadow, used for cards, popovers and floating
surfaces. Prefer flat surfaces separated by background tone over stacked shadows.

<!-- GEN:elevation -->

## Shapes

Two corner radii only. The small radius is the default for inputs and compact controls;
the large radius is used by buttons and secondary input styling. No pill or circle radius
tokens - circular elements (dots, pins, icon circles) are sized square by their component
styles.

<!-- GEN:shapes -->

## Components

Components are implemented as CSS classes shipped in `tikui.css` and documented per
component (base class, modifiers, elements, states, markup examples) in the catalog:

- Index of all components: `{DOMAIN}/ai/components-index.md`
- Full entries: `{DOMAIN}/ai/components/atom.md`, `…/molecule.md`, `…/organism.md`, `…/template.md`
- Utility modifier classes: `{DOMAIN}/ai/quarks.md` - icon glyphs: `{DOMAIN}/ai/icons.md`

The catalog is the source of truth for component markup. The token mapping below (also in
the front matter) is a styling summary of flagship components, extracted from the
compiled stylesheet:

<!-- GEN:components-table -->

## Do's and Don'ts

- **Do** load `tikui.css` (and the glyph font CSS) from the pattern-library host.
  **Don't** copy, fork or re-implement its styles inside application code.
- **Do** compose `araxxe-*` block/element classes with their leading-dash modifier
  classes (`class="araxxe-button -secondary"`). **Don't** invent new `araxxe-*` class
  names, restyle existing ones, or concatenate modifiers BEM-style.
- **Do** use quark modifier classes for spacing/sizing adjustments where a component's
  entry lists them. **Don't** write inline styles or custom CSS for anything the catalog
  covers.
- **Do** use status colors by meaning (danger = destructive/error, warning = caution,
  valid/success = positive, at-risk = attention). **Don't** pick them for decoration.
- **Do** use service colors to identify the matching Araxxe service line. **Don't** mix
  service colors outside their service context.
- **Do** use the Araxxe glyph font for icons (`{DOMAIN}/ai/icons.md`). **Don't** import
  third-party icon sets.
- **Do** reference the tokens in this file if a genuinely uncovered case needs custom
  CSS. **Don't** hardcode new hex values or font sizes in application styles.