AI Implementation Guide — Syhrezz Design System

Critical: Do NOT introduce Tailwind utility classes, Material UI, shadcn, Bootstrap, Ant Design, or any other design system into Syhrezz pages. Every component must use the class-based system defined in this design system. Every visual value must come from CSS custom properties defined in ds-tokens.css.

Design Identity Rules

Rule	Correct	Wrong
Font family	'Plus Jakarta Sans', sans-serif	Inter, Roboto, system-ui, -apple-system
Font for sales pages	'Poppins', sans-serif	Any other font
Primary CTA color (Accent)	#6366F1	#3B82F6, any blue
Primary CTA color (Dark)	#0F172A	Any other color
Page background	#F8FAFC (var(--surface))	#fff, #f5f5f5, #f0f0f0
Card background	#fff (var(--card))	Any tinted white
Sidebar background	#0F172A (primary role)	Any other dark color
Border color	#E2E8F0 (var(--border))	#d1d5db, #e5e7eb
Card border radius	20px (var(--r-4xl))	8px, 12px, 24px, 1rem
Button border radius	12px (default md)	4px, 6px, rounded-full
Icons	Inline SVG, Heroicons outline, stroke-width:2	Font Awesome, Lucide, emoji, img tags
Icon size in buttons	16px (md), 14px (sm), 18px (lg)	24px, 1em, 1rem

Page Layout Rules

Every Syhrezz page follows this exact structure: Fixed sidebar (left) + Fixed topbar (top, offset by sidebar width) + Scrollable main content area. The sidebar state (collapsed/expanded) is persisted in localStorage. Main content shifts when the sidebar collapses.

Element	CSS	Value
Sidebar width (expanded)	width	268px (Dark), 280px (Accent), 260px (supervisor)
Sidebar width (collapsed)	width	68px (primary role), 80px (Accent)
Sidebar position	position	fixed, left:0, top:0, height:100vh, z-index:1000
Topbar height	height	56–64px
Topbar position	position	fixed, top:0, left:[sidebar-width], right:0, z-index:100
Main margin	margin-left	Equal to sidebar width. Shifts on collapse.
Main padding-top	padding-top	Equal to topbar height
Content inner padding	padding	28px 32px (admin/director), 20px (mobile)
Content max-width	max-width	1400px, margin:0 auto

Component Rules

Buttons

Rule	Detail
Base class always required	Every button needs `.btn` + one variant class. Never just `.btn-primary` alone.
Hover lift	All variants use `transform:translateY(-2px)` on hover. Ghost is the exception — no lift.
Destructive actions	Danger buttons MUST trigger a confirmation modal before executing. Never fire delete directly.
Form submit	Use `type="submit"` for forms, `type="button"` for everything else.
Loading pattern	Add `.btn-loading` + prepend spinner element + change label text. Never just disable.
Icon-only buttons	Must have `aria-label` or `title` attribute.

Form Fields

Rule	Detail
Label style	Always UPPERCASE, 12px, fw-700, letter-spacing:0.5px, color:#64748B
Input class	Always use `.input` class. Also applies to `<select>` and `<textarea>`.
Focus ring	Always `0 0 0 3px rgba(59,91,219,.1)` — never a solid outline
Error state	Add `.input-error` to input AND render `.form-error-msg` div below it
Form group	Every field wrapped in `.form-group` with `margin-bottom:16px`
Icon in input	Wrap in `.input-wrap`, add `.has-icon-left` or `.has-icon-right` to input

Tables

Rule	Detail
Always wrapped	Table must be inside `.table-wrap`. Never a bare `<table>`.
Toolbar required	Every table has a `.table-toolbar` with title on left, actions on right.
User cell pattern	30px circle avatar + stacked name (13px fw-600) + email (11px #94A3B8)
Dates and IDs	Always use `font-family: var(--font-mono)` for dates, IDs, transaction numbers
Action buttons	Last column only. Use ghost-sm buttons, never full-size buttons in table rows.
Empty state	Every table must have an empty state that renders when data array is empty.
Pagination	Always include `.table-pagination` with count text left, page buttons right.

Modals

Rule	Detail
Overlay is flex container	The overlay div is `display:flex; align-items:center; justify-content:center`
Show/hide	Use `display:none` → `display:flex`. Never visibility or opacity alone.
Click outside	Add `onclick="if(event.target===this)this.style.display='none'"` to overlay
Escape key	Always add keydown listener for Escape to close modal
Body scroll lock	Set `document.body.style.overflow='hidden'` on open, restore on close
Footer order	Cancel/secondary always LEFT. Confirm/primary always RIGHT.
Destructive modals	Use `.btn-danger` for confirm button, never `.btn-primary`

Rule	Detail
Collapse state	Persisted in `localStorage` with key `{role}-sidebar-collapsed`
Active indicator	4px wide left border (absolute positioned), primary/accent color, glowing box-shadow
Label fade	On collapse: `opacity:0; transform:translateX(-10px)` transition on labels
Section labels	10px, fw-700–800, UPPERCASE, letter-spacing:1.5–2px, rgba(148,163,184,.35–.4)
Scrollbar	Sidebar nav uses hidden scrollbar: `scrollbar-width:none` + `::-webkit-scrollbar{display:none}`
Toggle button	Always at bottom of sidebar. State saved to localStorage on click.

Reusable Pattern Rules

Dashboard Page Pattern

/* Dashboard page structure — always in this order */

1. Page Header (h1 + subtitle + action buttons)
2. Optional Alert Banner (if system warnings exist)
3. KPI Grid (4 columns, gradient cards OR white stat cards)
4. Main Content Grid (2–3 column layout):
   - Charts / Target card
   - Follow-up list / Activity feed
5. Secondary Content Grid:
   - Data table (2/3 width)
   - Todo list + donut chart (1/3 width)

CRUD Table Page Pattern

1. Page Header (title + "Add [Item]" button)
2. Filter Bar (search input + select filters, flex wrap)
3. Table Wrap:
   - Toolbar (title + count + bulk actions + export + add button)
   - Table (checkbox col + data cols + badge col + actions col)
   - Pagination
4. Empty State (when data.length === 0)
5. Modal (for add/edit form)

Detail Page Pattern

1. Page Header (back button + entity name + status badge + actions)
2. Info Cards Grid (2 columns):
   - Left: Main info (name, contact, address, etc.)
   - Right: Stats/metrics, status, assigned rep
3. Tabs (Overview / Activities / Transactions / Contacts)
4. Tab content panels (each tab renders its own list/table)

Common Mistakes to Avoid

Mistake	Correct Approach
Using emoji as icons	Always use inline SVG with stroke="currentColor", no emoji anywhere in UI
Hardcoding hex values	Always use CSS custom properties: `var(--primary)`, `var(--border)`, etc.
Adding Tailwind classes	Use the design system class-based API exclusively
Two primary buttons side-by-side	One primary CTA max. Use outline for secondary actions.
Bare table element	Always wrap in `.table-wrap` with toolbar and pagination
Nesting cards inside cards	Use sections or dividers within a single card
Full-saturation badge backgrounds	Always use the soft `-bg` token with its matching `-text` token
Hardcoded font-family strings	Use `var(--font-primary)` or `var(--font-mono)`
Large border-radius on buttons	Buttons use 12px (md), 10px (Dark), 8px (sm), 7px (xs) — not rounded-full
Delete without confirmation	All destructive actions require a confirmation modal with .btn-danger
Sidebar without localStorage	Always persist collapse state to localStorage
Using img tags for icons	Inline SVG only — no icon fonts, no img tags, no emoji

Recommended AI Prompt

When working with an AI assistant on a new Syhrezz page, provide this context at the start of your conversation:

I am building a page using the Syhrezz Design System. Follow these rules exactly:

VISUAL IDENTITY (non-negotiable):
- Font: 'Plus Jakarta Sans', sans-serif (primary UI) — 'Poppins' for alternative role pages
- Primary accent: #6366F1 (default) | Dark accent: #0F172A | Blue accent: #2563EB
- Page background: #F8FAFC | Card background: #FFFFFF | Border color: #E2E8F0
- Card radius: 20px | Button radius: 12px (md), 8px (sm) | Badge/pill: 999px
- All values must use CSS custom properties from ds-tokens.css — NEVER hardcode hex values

LAYOUT:
- Fixed dark sidebar (268px) + Fixed topbar (56px) + Scrollable main content area
- Sidebar collapses to 68px, state persisted in localStorage
- Content max-width: 1400px, padding: 28px 32px

ICONS:
- ALWAYS inline SVG, Heroicons outline style, stroke-width:2, stroke="currentColor"
- NEVER use emoji, icon fonts, or img tags for icons

COMPONENTS:
- Buttons: always .btn + .btn-{variant} — never bare unstyled buttons
- Tables: always inside .table-wrap with toolbar + pagination
- Modals: overlay is flex container, display:none/flex toggle, cancel LEFT / confirm RIGHT
- Badges: always soft bg+text token pairs — never full-saturation backgrounds
- Forms: labels UPPERCASE 12px fw-700 letter-spacing:.5px, .input class for all fields, .form-group wrapper
- See the Syhrezz Design System documentation for full component reference