# Amin Rayan Design System

Single source of truth for layout, components, tokens, motion, responsive behavior, accessibility, and coding conventions across the Amin Rayan (aminrayan) Next.js site.

This documentation does **not** redesign the product. It codifies what already exists in code so every future UI change stays visually and technically consistent.

---

## Purpose

- Prevent ad-hoc containers, colors, spacing, and typography.
- Make Shadcn / Tailark imports adapt to project tokens before shipping.
- Give developers and Cursor Agents one place to look before writing UI.
- Keep light/dark themes, RTL Persian readability, and accessibility as non-negotiable defaults.

---

## Source of truth (code)

| Concern | Canonical location |
| --- | --- |
| CSS tokens (color, radius, button metrics) | `app/globals.css` |
| Layout container & section rhythm | `lib/layout.ts`, `components/container.tsx` |
| Typography scale | `lib/typography.ts`, `components/ui/typography.tsx` |
| Button system | `components/ui/button.tsx` |
| Card system | `components/ui/card.tsx` |
| Scroll motion | `lib/block-motion.ts`, `components/motion-reveal.tsx` |
| Theme | `components/theme-provider.tsx` (`next-themes`, class strategy) |
| Cursor enforcement | `.cursor/rules/*.mdc` |

When docs and code disagree, **update the docs to match code** (or fix code via an intentional design change)—never invent a second system.

---

## Documentation hierarchy

```
docs/design-system/
├── README.md              ← you are here (entry point)
├── layout.md              ← page structure
├── grid.md
├── container.md
├── spacing.md
├── colors.md
├── typography.md
├── buttons.md
├── forms.md
├── cards.md
├── navbar.md
├── hero.md
├── sections.md
├── footer.md
├── icons.md
├── images.md
├── motion.md
├── gradients.md
├── glassmorphism.md
├── dark-mode.md
├── responsive.md
├── accessibility.md
├── shadcn.md
├── coding-rules.md
└── quality-checklist.md   ← gate before every UI PR
```

---

## Priority order

When two guidelines conflict, follow this order:

1. **Accessibility** (`accessibility.md`) — contrast, focus, keyboard, reduced motion, touch targets.
2. **Layout & container** (`layout.md`, `container.md`, `grid.md`) — never invent a second content width.
3. **Semantic tokens** (`colors.md`, `spacing.md`, `typography.md`) — never hardcode hex or arbitrary spacing.
4. **Component systems** (`buttons.md`, `cards.md`, `forms.md`, …) — reuse existing primitives.
5. **Visual effects** (`gradients.md`, `glassmorphism.md`, `motion.md`) — decorative only; never break layout.
6. **Imported blocks** (`shadcn.md`) — adapt third-party UI to the above; never ship vendor styles as-is.

---

## How developers should use this

1. Before any UI task, open this README and the relevant topic docs.
2. Reuse `Container`, `layout.*`, `type.*` / `<Typography>`, `Button`, and `Card`.
3. Prefer semantic Tailwind classes (`bg-primary`, `text-muted-foreground`, `border-border`) over raw values.
4. For new sections, copy the section shell pattern from `sections.md`.
5. Run through `quality-checklist.md` before opening a PR.

### Quick imports

```tsx
import { Container } from "@/components/container";
import { layout } from "@/lib/layout";
import { type, typeSpacing } from "@/lib/typography";
import { Button } from "@/components/ui/button";
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
import { cn } from "@/lib/utils";
```

---

## How Cursor should follow this

Cursor Rules under `.cursor/rules/` enforce the same standards automatically:

| Rule file | Scope |
| --- | --- |
| `layout-container.mdc` | Containers & section width |
| `frontend.mdc` | Tokens, reuse, dark mode, coding conventions |
| `ui-design.mdc` | Visual consistency, spacing, motion, components |
| `accessibility.mdc` | A11y non-negotiables |
| `shadcn.mdc` | Adapting imported Shadcn/Tailark blocks |

Agents must:

- Read these docs when building or changing UI.
- Never invent a second container, color palette, spacing scale, or button style.
- Always support light and dark themes via semantic tokens.
- Always preserve RTL-friendly typography and responsive behavior.

---

## Brand snapshot

| Token | Value | Role |
| --- | --- | --- |
| Primary | `#29a19c` | CTAs, focus ring, links |
| Primary dark / secondary | `#044343` | Deep brand panels, secondary surfaces |
| Neutral | `#222222` | Body text (light) |
| Gray | `#999999` | Muted accents |
| Light | `#e4e4e4` | Borders / muted fills (light) |
| Font | IRANSansX | Site-wide Persian UI |

---

## Related skills (optional)

Project skills under `.cursor/skills/` (design-system, ui-styling, brand) can assist generation, but **this folder wins** for Amin Rayan product UI.