139 lines
4.8 KiB
Markdown
139 lines
4.8 KiB
Markdown
|
# 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.
|