aragrp/docs/design-system/README.md

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

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.