# AGENTS.md — GINI brand project

> Guidance for AI coding agents (Claude Code, Cursor Agents, Codex, v0).
> A short briefing of everything an agent needs to operate safely inside
> any codebase that uses the GINI brand.

## Mission

You're contributing to a digital product under the **GINI** brand.
Read the full identity at https://gini.iq/brand before producing anything.

## Authoritative sources

- JSON manifest: https://gini.iq/brand.json (full machine-readable copy)
- Markdown book: https://gini.iq/brand.md (same content as prose)
- CSS variables: https://gini.iq/brand.css
- Tailwind tokens: https://gini.iq/brand.tailwind.css
- W3C tokens: https://gini.iq/brand.tokens.json
- Model system prompt: https://gini.iq/brand-prompt.md
- Logo files (8 SVG variants): https://gini.iq/brand/
- Mascot pack (42 PNG poses): https://gini.iq/brand/mascots/
- Design system (live specimens): https://gini.iq/en/brand#design-system
- Component classes (every skeu-* class): https://gini.iq/skeu.css
- Component library (64 live components with copy-ready code): https://gini.iq/en/brand#components

## Design system — modern skeuomorphism (Precision Instrument)

Every element is built as if it were a real physical object — raised, pressed, engraved or lit — with the restraint of a contemporary digital product.

**Core rules:**
- A single virtual light, upper-left. Raised surfaces get an inner top highlight (inset 0 1px 0 white), a short contact shadow beneath, and a softer ambient shadow further out. Recessed surfaces invert the logic: a dark inner shadow at the top and a light lip at the bottom.
- **Real-world physical logic** — Before designing any element we ask: if this were a real object, how would it behave? Buttons press, switches slide, fields are recessed, cards sit on the surface, the selected tab is seated in its rail.
- **One light source** — Light always comes from the upper-left, slightly frontal. Every shadow and every highlight respects that direction, so the whole interface reads as one object.
- **Restraint over spectacle** — Only four material families, only eight elevation levels, grain that is felt rather than noticed. Depth hierarchy matters more than the quantity of shadows.
- **A clear depth hierarchy** — Base → recessed functional areas → raised content surfaces → physical controls → floating overlays. Users understand it without thinking.
- **Clarity always wins** — Typography stays modern and clean with no text shadows, and information density is preserved. When beauty and legibility conflict, legibility wins — with a premium physical touch.
- **Accessibility is non-negotiable** — State is never communicated by shadow alone: a visible focus rim on every control, ARIA on segmented controls and menus, touch targets ≥ 44px, and reduced-motion respected.

**Materials (use the ready class, never invent shadows):**
- Matte polymer → `body / .skeu-well` — Page base, recessed trays and wells, input fields
- Raised ceramic → `.skeu-panel / .skeu-panel-2 / .skeu-rail / .skeu-dialog` — Cards, panels, the navigation rail, dialogs, secondary buttons
- Anodized orange → `.skeu-btn-primary / .skeu-tile / .skeu-tab-active / .skeu-chip-solid` — The primary button, icon tiles, the active tab, solid badges, the ON switch
- Graphite → `.skeu-dark / .skeu-btn-dark` — The footer, code windows, dark CTA blocks and the controls on them

**Elevation levels:** Recessed (`.skeu-well`) · Well (`.skeu-input / .skeu-well-soft`) · Flush (`.skeu-btn-ghost / .skeu-list-item`) · Raised 1 (`.skeu-panel`) · Raised 2 (`.skeu-panel-2 / .skeu-rail`) · Floating (`.skeu-floating`) · Overlay (`.skeu-dialog`) · Pressed (`:active / .skeu-tab-active`)
**Radii:** 6px Tiny chips and tags · 10px Standard buttons, inputs, small controls · 14px Tiles and tabs · 20px Cards and panels · 26px Dialogs and the navigation rail

**Do:**
- Start with the material class (skeu-panel, skeu-btn-primary…) then add Tailwind utilities for layout only.
- Let content (product imagery, numbers, copy) be the hero; surfaces support it.
- Use logical properties (start/end) and check both the Arabic and English versions.
- Give every state (hover, pressed, focus, disabled) a clear physical expression.
- Respect the elevation level that matches the element's role — don't raise everything.
**Don't:**
- No neumorphism: grey blobs with a light shadow top-left and a dark shadow bottom-right.
- No leather, wood or heavy image textures — materials are refined and restrained.
- No decorative gradients without a physical reason, and no ad-hoc shadows outside the tokens.
- Don't make everything a pill — each object type has its radius.
- No text shadows, and never trade contrast for softness.
- No Tailwind rtl:/ltr: variants — the root is hard-coded RTL and they leak into the English version.

Full reference: https://gini.iq/en/brand#design-system — live implementation: app/globals.css

## Component library

Install in one line — `<link rel="stylesheet" href="https://gini.iq/skeu.css">` — next to
`https://gini.iq/brand.css` for the palette. Copy a component from the
library instead of building it from scratch:

- **Actions:** Primary button — three sizes, Button family, Icon button, Button with leading icon, Loading button, Disabled button, Button group / split button, Floating action button
- **Forms:** Text field with label, help and error, Input with leading icon, Search field, Select, Textarea, Checkbox list, Radio group, Switch row, Segmented control, Slider, File drop zone, OTP / code row, Date input, Two-column form layout, Inline validation summary
- **Navigation:** Navbar (rail), Breadcrumb, Tabs — underline and segmented, Pagination, Stepper / progress steps, Sidebar list, Bottom mobile tab bar, Back button
- **Data display:** KPI tile, Stat row with delta chip, Product card, Pricing card, Feature card, Testimonial card, User card + avatar group, Table with header, rows and actions, Description list, Timeline, Badges and chips, Progress bar + circular progress, Meter / gauge, Empty state, Skeleton set, List rows with chevrons
- **Feedback & overlays:** The four semantic alerts, Toast, Inline banner, Modal dialog (live), Dropdown menu (live), Tooltip, Popover, Confirm dialog (live), Bottom sheet (live)
- **Commerce:** Order status pills, Cart line item, Price + discount, Quantity stepper, Delivery timeline, Merchant header card, Payment method row, Coupon / loyalty points chip

Full HTML for every component: https://gini.iq/en/brand.md ("Component library").

## Before any commit

- Do not change the primary colour #F05D25.
- Do not introduce typefaces other than Rubik.
- Do not replace `bg-primary` with `bg-[#F05D25]` (breaks the token).
- Arabic copy: `leading-snug` minimum.
- 3–5 colours per design — no more.
- Only use logos from `/brand/` — switch to mono variants when the
  brand orange would clash with the surrounding fill.
- Only use mascot poses from `/brand/mascots/` — do not redraw,
  recolour, or generate new poses.
- Start every UI element from a `skeu-*` material class; never add
  shadows outside the `--skeu-shadow-*` tokens.

## License

Brand assets are licensed for editorial and approved-partner use. For
commercial co-branding, contact info@gini.iq.

## Version

Current brand protocol: v1.7 (2026-09)