igny8/DESIGN-GUIDE.md

IGNY8 Design System Guide

Single Source of Truth for UI Components

This guide ensures consistent, maintainable frontend code across the entire application.

---

Quick Links

Resource	Path	Description
Component System	docs/30-FRONTEND/COMPONENT-SYSTEM.md	Full component reference with props, examples, and usage
ESLint Plugin	frontend/eslint/	Custom rules enforcing design system
Live Demo	/ui-elements route	Interactive component showcase
Design Tokens	frontend/src/styles/design-system.css	CSS variables and tokens
Icons	frontend/src/icons/	All SVG icons

---

Core Principles

1. Use Components, Never Raw HTML

// ❌ NEVER
<button className="...">Click</button>
<input type="text" className="..." />
<select className="...">...</select>
<textarea className="..."></textarea>

// ✅ ALWAYS
<Button variant="primary">Click</Button>
<InputField type="text" label="Name" />
<Select options={options} />
<TextArea rows={4} />

2. Import Icons from Central Location

// ❌ NEVER
import { XIcon } from '@heroicons/react/24/outline';
import { Trash } from 'lucide-react';

// ✅ ALWAYS
import { CloseIcon, TrashBinIcon } from '../../icons';

3. Consistent Sizing

// Icons in buttons/badges
<Icon className="w-4 h-4" />

// Standalone icons
<Icon className="w-5 h-5" />

// Large/header icons
<Icon className="w-6 h-6" />

---

Component Quick Reference

Need	Component	Import
Action button	Button	components/ui/button/Button
Icon-only button	IconButton	components/ui/button/IconButton
Text input	InputField	components/form/input/InputField
Checkbox	Checkbox	components/form/input/Checkbox
Radio	Radio	components/form/input/Radio
Dropdown	Select	components/form/Select
Multi-line text	TextArea	components/form/input/TextArea
Toggle	Switch	components/form/switch/Switch
Status label	Badge	components/ui/badge/Badge
Container	Card	components/ui/card/Card
Popup	Modal	components/ui/modal
Loading	Spinner	components/ui/spinner/Spinner
Notification	useToast	components/ui/toast/ToastContainer

→ See COMPONENT-SYSTEM.md for full props and examples

---

ESLint Enforcement

Rules

Rule	Level	Action
no-raw-button	warn → error	Use Button or IconButton
no-raw-input	warn → error	Use InputField, Checkbox, Radio
no-raw-select	warn → error	Use Select or SelectDropdown
no-raw-textarea	warn → error	Use TextArea
no-restricted-imports	error	Block external icon libraries

Check Violations

cd frontend
npm run lint

Plugin Location

The custom ESLint plugin is at: frontend/eslint/eslint-plugin-igny8-design-system.cjs

---

For AI Agents

When working on this codebase:

1. Read first: docs/30-FRONTEND/COMPONENT-SYSTEM.md
2. Never use: <button>, <input>, <select>, <textarea> tags
3. Import icons from: src/icons only
4. Verify after changes: npm run lint
5. Reference pages: Planner and Writer modules use correct patterns

Correct Import Paths

// From a page in src/pages/
import Button from '../components/ui/button/Button';
import IconButton from '../components/ui/button/IconButton';
import InputField from '../components/form/input/InputField';
import { PlusIcon, CloseIcon } from '../icons';

// From a component in src/components/
import Button from '../../components/ui/button/Button';
import { PlusIcon } from '../../icons';

// From a nested component
// Adjust ../ based on depth

---

File Structure

frontend/
├── eslint/
│   └── eslint-plugin-igny8-design-system.cjs  # Custom rules
├── src/
│   ├── components/
│   │   ├── ui/           # Display components
│   │   │   ├── button/   # Button, IconButton
│   │   │   ├── badge/    # Badge
│   │   │   ├── card/     # Card
│   │   │   ├── modal/    # Modal
│   │   │   └── ...
│   │   └── form/         # Form components
│   │       ├── input/    # InputField, Checkbox, Radio, TextArea
│   │       ├── switch/   # Switch
│   │       ├── Select.tsx
│   │       └── ...
│   ├── icons/            # All SVG icons
│   │   └── index.ts      # Export all icons
│   └── styles/
│       └── design-system.css  # Design tokens
docs/
└── 30-FRONTEND/
    └── COMPONENT-SYSTEM.md    # Full component documentation

---

Migration Checklist

When fixing violations:

• Replace <button> with Button or IconButton
• Replace <input type="text/email/password/number"> with InputField
• Replace <input type="checkbox"> with Checkbox
• Replace <input type="radio"> with Radio
• Replace <select> with Select or SelectDropdown
• Replace <textarea> with TextArea
• Replace external icon imports with src/icons
• Run npm run lint to verify
• Run npm run build to confirm no errors