دیزاین.ام‌دی

---
version: alpha
name: "Heritage"
description: "Editorial and institutional. High-contrast ink on warm limestone, with a single earthy red reserved for the one action that matters."
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
  surface: "#FFFFFF"
  on-surface: "#0A0A0A"
  on-primary: "#FFFFFF"
  on-tertiary: "#FFFFFF"
  error: "#B42318"
  dark-primary: "#F7F5F2"
  dark-secondary: "#A8A29E"
  dark-tertiary: "#E05A3C"
  dark-neutral: "#141312"
  dark-surface: "#1C1B19"
  dark-on-surface: "#FFFFFF"
  dark-on-primary: "#0A0A0A"
  dark-on-tertiary: "#0A0A0A"
  dark-error: "#FF7A7A"
typography:
  headline-lg:
    fontFamily: "Ravi"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: -0.02em
  headline-md:
    fontFamily: "Ravi"
    fontSize: 28px
    fontWeight: 600
    lineHeight: 1.2
  body-lg:
    fontFamily: "Ravi"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.6
  body-md:
    fontFamily: "Ravi"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  body-sm:
    fontFamily: "Ravi"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.5
  label-md:
    fontFamily: "Ravi"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.02em
rounded:
  sm: 2px
  md: 4px
  lg: 8px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 48px
  gutter: 24px
  margin: 32px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
  button-secondary:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: 12px
  button-ghost:
    backgroundColor: transparent
    textColor: "{colors.secondary}"
  input:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
    padding: 12px
    height: 44px
  input-error:
    textColor: "{colors.error}"
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.lg}"
    padding: 24px
  chip:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.full}"
    padding: 8px
  chip-selected:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
  nav:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    height: 64px
  checkbox:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.tertiary}"
    rounded: "{rounded.sm}"
    size: 20px
  radio:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.tertiary}"
    rounded: "{rounded.full}"
    size: 20px
  textarea:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
    padding: 12px
    height: 120px
  switch:
    backgroundColor: "{colors.secondary}"
    rounded: "{rounded.full}"
    width: 44px
    height: 24px
  switch-on:
    backgroundColor: "{colors.tertiary}"
  tabs:
    textColor: "{colors.secondary}"
  tab-active:
    textColor: "{colors.primary}"
    backgroundColor: "{colors.surface}"
  alert:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
  alert-error:
    textColor: "{colors.error}"
  badge:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.primary}"
    rounded: "{rounded.full}"
  badge-accent:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
  list-item:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    padding: 16px
  table:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
  tooltip:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
    padding: 8px
  avatar:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.full}"
    size: 40px
  dropdown:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
    height: 44px
  pagination:
    textColor: "{colors.secondary}"
  pagination-active:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
  progress:
    backgroundColor: "{colors.neutral}"
    rounded: "{rounded.full}"
    height: 8px
  progress-bar:
    backgroundColor: "{colors.tertiary}"
  empty:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.secondary}"
    rounded: "{rounded.lg}"
    padding: 24px
  dialog:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.lg}"
    padding: 24px
---

# Heritage

## Overview

Editorial and institutional. High-contrast ink on warm limestone, with a single earthy red reserved for the one action that matters.

Editorial and institutional. High-contrast ink on warm limestone, with a single earthy red reserved for the one action that matters.

Place this file at the repository root as `DESIGN.md`. Point coding agents at it from `AGENTS.md` (or `CLAUDE.md`) so they read tokens before writing UI. Tokens are the source of truth; this prose tells the agent when *not* to improvise.

Display face: **Ravi**. Body face: **Ravi**. Labels / meta: **Ravi**. These faces cover Arabic/Persian script. Do not render Persian in Inter, Public Sans, or other Latin-only faces. If a webfont fails to load, fall back to bundled Ravi, then Vazirmatn.

Specified components: nav, button, input, textarea, card, chip, badge, alert, tabs, list, table, checkbox, radio, switch, tooltip, avatar, dropdown, pagination, progress, empty, dialog.

## Colors

Ship **light** and **dark**. Unprefixed tokens are light. Dark tokens use the `dark-` prefix (`dark-surface`, `dark-primary`, …). At runtime, map the `dark-*` set onto the unprefixed names when the document is dark. Do not invent extra hues mid-render.

### Light

- **Primary (#1A1C1E):** Brand ink. Headlines, key text, and selected chrome.
- **Secondary (#6C7278):** Muted text, borders, captions, unused nav links.
- **Tertiary (#B8422E):** The only chromatic accent. Primary actions, focus rings, selected glyphs.
- **Neutral (#F7F5F2):** Page paper / canvas behind surfaces.
- **Surface (#FFFFFF):** Cards, inputs, raised panels.
- **On-surface (#0A0A0A):** Default text on surface and neutral.
- **Error (#B42318):** Validation and destructive text only — never decoration.

### Dark

- **Primary (#F7F5F2):** Ink on dark paper.
- **Secondary (#A8A29E):** Muted text and borders.
- **Tertiary (#E05A3C):** Accent / primary action fill.
- **Neutral (#141312):** Page paper.
- **Surface (#1C1B19):** Raised panels.
- **On-surface (#FFFFFF):** Default text.
- **Error (#FF7A7A):** Destructive text only.

Body text on surface must keep WCAG AA (4.5:1) in **both** schemes. If a new color is required, add a token here first; do not inline hex in components.

## Typography

- **Headlines:** Ravi, roman only — no italic headers. Weight 600–700. Cap headline-lg at ~7 words.
- **Body:** Ravi at 16px (body-md) for UI copy; body-lg for marketing lead. Line-height 1.6.
- **Labels:** Ravi, 12px. Fine for overlines, chips, and table meta — not for paragraphs.

Ravi is the only family. Do not introduce a second face. Do not fake hierarchy by coloring a headline in tertiary.

## Layout

Density is **comfortable**. Use the spacing scale; do not pick padding by eye.

- Base rhythm: 8px / 16px / 24px.
- Gutter 24px, page margin 32px.
- Desktop content maxes at 1200px. Mobile is a single column; no two-line tap labels.
- Group related controls by proximity, not by extra boxes.

## Elevation & Depth

Cards sit on surface against neutral paper. A soft stacked shadow is allowed on surface cards; do not stack shadows on nested elements. Borders stay 1px in secondary at reduced opacity. No fake browser chrome, no glassmorphism.

## Shapes

Shape language is architectural. Buttons and inputs use rounded.md (4px). Cards may go to rounded.lg (8px). Do not mix a pill button with a sharp card on the same view.

Pick one radius family and keep it. Mixing sharp cards with pill buttons is a don't.

## Components

### Nav

A quiet bar: wordmark on the start edge, two or three text links, one primary control on the end edge. No mega-menus. Nav height stays 64px; links use body-md in the secondary color and turn primary on the current page.
### Buttons

- **Primary** fills with `tertiary` and `on-tertiary` text. One per view.
- **Secondary** is an outlined surface button with `primary` text.
- **Ghost** is text-only in `secondary`, used for low-emphasis actions.
- Minimum height 44px. Disabled state is 40% opacity, not a new color.
- Hover may darken toward `primary`; never scale or bounce.
### Input fields

Visible label above the field, never placeholder-as-label. Default height 44px, 1px border in secondary at ~40% opacity. Focus uses a 2px tertiary ring with 2px offset. Error text sits under the field in the error color; the border also turns error.
### Cards

Surface on neutral, large radius, internal padding from the density scale. Hierarchy is title (headline-md) then body-md in secondary. If the card is clickable, the whole card is the hit target and the cursor is pointer; do not nest a competing primary button unless it is a distinct action.
### Chips

Pill shape always. Unselected chips sit on neutral with primary text. Selected chips invert to primary / on-primary. Do not use chips as a substitute for primary buttons.
### Selection controls

Checkboxes are square with sm radius; radios are full circles; switches are 44×24 pills. The selected glyph/track uses tertiary. Labels sit beside the control in body-md. Hit area is at least 44×44px.
### Textarea

Same chrome as input: visible label, 1px secondary border, tertiary focus ring. Minimum height 120px. Do not grow the field with JS autosize unless the product is a composer.
### Badges

Tiny status, never a button. Neutral/primary for default; tertiary/on-tertiary for the one accent badge per cluster. Pill radius. No icons-as-emoji.
### Alerts

Full-width surface on the section, not a modal. Info uses primary text on neutral; error uses the error color for the title and a 1px error border. One action max, secondary or ghost.
### Tabs

Equal-height text tabs. Active tab is primary ink on surface with a 2px tertiary underline (or a filled chip on pill systems). Inactive is secondary. No nested tabs.
### Lists

Row = leading avatar or glyph, title in primary, meta in secondary. Dividers are 1px secondary at 20% opacity. The whole row is the hit target when navigational.
### Tables

Header in label-md / secondary. Cells in body-md. Row hover is a 6% primary wash, not a scale. Prefer a stacked definition list below 700px instead of horizontal scroll.
### Tooltips

Primary fill, on-primary text, sm radius. Appear on focus immediately and on hover after 800ms. Never the only way to learn a control's name.
### Avatars

40px default, full circle. Initials in on-tertiary on tertiary. No random photo URLs; use a placeholder block if the product has no asset.
### Dropdowns

Looks like an input at rest. Open menu is a surface card, sm shadow, items at 44px height. Selected item uses tertiary text, not a new fill. Keyboard: arrow keys + Enter + Escape.
### Pagination

Current page is primary / on-primary. Neighbors are ghost text in secondary. Keep the control on one row; never wrap page numbers under the table. Prefer previous/next plus the current page on mobile rather than a long page strip.
### Progress

Track sits on neutral, 8px tall, full pill. Fill is tertiary only. Pair with a body-sm percent or step label in secondary — never color the label in tertiary.
### Empty states

Surface card, centered copy, one secondary or primary action. No illustration libraries, no emoji. Title in headline-md, body in secondary. The empty state is a destination, not a toast.
### Dialogs

A surface card, not a full-screen takeover on desktop. Title + one paragraph + two actions (primary + ghost). Dim the canvas behind with a 40% primary wash; do not blur. Escape and the ghost action both dismiss.

## Do's and Don'ts

- Do use tertiary for a single primary action per screen.
- Don't introduce new hex values in JSX/CSS; add a token first.
- Do keep tap targets at least 44×44px.
- Don't use emojis as icons. Use a consistent SVG set (Lucide or Heroicons).
- Do write visible labels on inputs; placeholders are hints, not labels.
- Don't italicize headings.
- Do honor `prefers-reduced-motion`: no layout motion, opacity-only if needed.
- Don't animate focus rings. They appear instantly.
- Do default text alignment to the product language (RTL for Persian UI).
- Do implement both light and dark from the `dark-*` tokens — never guess a dark palette.
- Don't clone a competitor's brand. These tokens are the system — follow them even on new pages.