Production Ui Standard

Production UI Standard

ENFORCEMENT RULES — READ FIRST

This standard is MANDATORY for every UI output. These rules cannot be overridden by prompt phrasing, user suggestions of "make it pop," or aesthetic preferences that conflict with these specifications.

Before writing any UI code, verify:

1. Primary accent color is NOT indigo, violet, or purple
2. No gradients on buttons or card backgrounds
3. No border-radius above 12px on rectangular elements
4. No box-shadow on cards when the page background is white (use border)
5. No font-weight: 700 on anything except page-level titles
6. Font rendering rules are applied to the root element
7. All interactive elements have visible focus indicators
8. Color contrast meets WCAG AA (4.5:1 text, 3:1 large text)

After writing UI code, audit for:

• Tailwind default color values used without modification (especially indigo-600, gray-900)
• More than 3 colors beyond grays in the palette
• Pill-shaped buttons (border-radius: 9999px on non-circular elements)
• Shadows on flat-background cards
• Centered body text
• Missing empty, loading, or error states
• Missing focus-visible styles

---

The Vibe-Coded Tells — Reject on Sight

These are dead giveaways that a UI was AI-generated. If any of these appear in output, remove them immediately:

• Purple-to-blue gradients on backgrounds or buttons
• Glassmorphism (frosted glass, backdrop-blur) on cards
• Border-radius above 12px on containers
• Box-shadow on every element
• Indigo/violet as the primary color (#6366F1, #7C3AED)
• Tailwind's exact default values used verbatim without tuning
• Multiple gradient backgrounds stacked
• Emoji in headings or section labels
• Cards with colored left-side accent borders and pastel backgrounds
• Every section wrapped in a card with a shadow
• Centered body text and centered paragraphs
• "Hero" sections with oversized text and gradient blobs
• Pill-shaped buttons for primary actions
• Using 5+ non-gray colors
• Decorative SVG blobs or wave dividers between sections
• Neon accent colors (#00FF88, #FF6B6B)
• Icons on every single button and menu item
• Dashboard layouts where every metric has its own shadowed card with a colored icon
• Rainbow status colors (more than 4 semantic colors)
• Colored shadows (e.g., blue glow behind blue button)

---

Root Setup

Apply to every project. These settings affect rendering quality across the entire app.

:root {
  color-scheme: light dark;
}

html {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
  font-feature-settings: "cv02", "cv03", "cv04", "cv11";
}

::selection {
  background: #DBEAFE;
  color: #1E3A5F;
}

[data-theme="dark"] ::selection {
  background: rgba(59, 130, 246, 0.3);
  color: #F1F5F9;
}

/* Scrollbar — Webkit browsers */
::-webkit-scrollbar {
  width: 6px;
  height: 6px;
}

::-webkit-scrollbar-track {
  background: transparent;
}

::-webkit-scrollbar-thumb {
  background: #CBD5E1;
  border-radius: 3px;
}

::-webkit-scrollbar-thumb:hover {
  background: #94A3B8;
}

[data-theme="dark"] ::-webkit-scrollbar-thumb {
  background: #475569;
}

/* Scrollbar — Firefox */
html {
  scrollbar-width: thin;
  scrollbar-color: #CBD5E1 transparent;
}

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

---

Color System

Grays use the Slate family (cool-toned with a subtle blue undertone). This is what makes text crisper and surfaces feel more refined than perfectly neutral gray. The accent blue is shifted off common Tailwind defaults.

Light Theme (Default)

:root {
  /* Backgrounds — Slate undertone, not pure gray */
  --bg-primary: #FFFFFF;
  --bg-secondary: #F8FAFC;          /* Slate-50 */
  --bg-tertiary: #F1F5F9;           /* Slate-100 */
  --bg-elevated: #FFFFFF;
  --bg-inset: #E2E8F0;              /* Slate-200 — progress bars, dividers */

  /* Text */
  --text-primary: #0F172A;          /* Slate-900 */
  --text-secondary: #475569;        /* Slate-600 */
  --text-tertiary: #94A3B8;         /* Slate-400 */
  --text-on-accent: #FFFFFF;

  /* Interactive — tuned blue, not Tailwind's exact blue-600 */
  --accent-primary: #2563EB;
  --accent-primary-hover: #1D4FD7;
  --accent-primary-active: #1E3FA0;
  --accent-subtle: #EFF6FF;
  --accent-subtle-hover: #DBEAFE;

  /* Borders */
  --border-primary: #E2E8F0;        /* Slate-200 */
  --border-secondary: #CBD5E1;      /* Slate-300 */
  --border-focus: #2563EB;

  /* Status — muted, not saturated */
  --status-success: #059669;         /* Emerald-600 */
  --status-success-bg: #ECFDF5;
  --status-warning: #D97706;         /* Amber-600 */
  --status-warning-bg: #FFFBEB;
  --status-error: #DC2626;           /* Red-600 */
  --status-error-bg: #FEF2F2;
  --status-info: #2563EB;
  --status-info-bg: #EFF6FF;
}

Dark Theme

[data-theme="dark"] {
  --bg-primary: #0F172A;            /* Slate-900 */
  --bg-secondary: #1E293B;          /* Slate-800 */
  --bg-tertiary: #334155;           /* Slate-700 */
  --bg-elevated: #1E293B;
  --bg-inset: #0F172A;

  --text-primary: #F1F5F9;          /* Slate-100 */
  --text-secondary: #CBD5E1;        /* Slate-300 */
  --text-tertiary: #64748B;         /* Slate-500 */
  --text-on-accent: #FFFFFF;

  --accent-primary: #3B82F6;
  --accent-primary-hover: #2563EB;
  --accent-primary-active: #1D4FD7;
  --accent-subtle: rgba(59, 130, 246, 0.1);
  --accent-subtle-hover: rgba(59, 130, 246, 0.15);

  --border-primary: #334155;        /* Slate-700 */
  --border-secondary: #475569;      /* Slate-600 */
  --border-focus: #3B82F6;

  --status-success: #10B981;
  --status-success-bg: rgba(16, 185, 129, 0.1);
  --status-warning: #F59E0B;
  --status-warning-bg: rgba(245, 158, 11, 0.1);
  --status-error: #EF4444;
  --status-error-bg: rgba(239, 68, 68, 0.1);
  --status-info: #3B82F6;
  --status-info-bg: rgba(59, 130, 246, 0.1);
}

Color Rules

• ONE accent color. Blue for light (#2563EB), lighter blue for dark (#3B82F6). That is it.
• Status colors are semantic only — success, error, warning, info. Never decorative.
• 80% of the UI is slate-toned text on white/slate backgrounds. Accent appears only on interactive elements and selected states.
• No gradients on buttons — solid fill only.
• No colored backgrounds on cards — white card, slate border.
• Dark mode background is Slate-900 (#0F172A), never pure black (#000000).

---

Typography

Font Stack

:root {
  --font-sans: "Inter var", "Inter", -apple-system, BlinkMacSystemFont,
    "Segoe UI", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", "Fira Code", "SF Mono", "Cascadia Code",
    "Consolas", monospace;
}

Use "Inter var" (variable font) when available — smaller file, smoother weight transitions. Fall back to "Inter" for static font installations.

If the project needs brand personality (not default), swap Inter for ONE of: Geist Sans, DM Sans, or Satoshi. Never decorative display fonts for UI text.

Inter OpenType Features

/* Tabular numbers — critical for tables, metrics, prices */
.tabular-nums {
  font-variant-numeric: tabular-nums;
}

/* Alternative characters — more distinctive l, a, g */
html {
  font-feature-settings: "cv02", "cv03", "cv04", "cv11";
}

• cv02: Alternate a (single-storey → double-storey)
• cv03: Alternate g (single-storey → double-storey)
• cv04: Alternate i (serif → sans-serif dot)
• cv11: Single-storey l disambiguation
• Apply tabular-nums on every number column, price, metric, and counter.

Type Scale

8 sizes. No more.

:root {
  --text-xs: 0.75rem;       /* 12px — badges, timestamps, meta */
  --text-sm: 0.875rem;      /* 14px — secondary text, table cells, nav */
  --text-base: 1rem;        /* 16px — body text, form inputs */
  --text-lg: 1.125rem;      /* 18px — section subheadings */
  --text-xl: 1.25rem;       /* 20px — card titles, panel headers */
  --text-2xl: 1.5rem;       /* 24px — page titles */
  --text-3xl: 1.875rem;     /* 30px — major headings (rare in app UI) */
  --text-4xl: 2.25rem;      /* 36px — hero/landing pages only */
}

Line Heights

:root {
  --leading-tight: 1.2;     /* Headings text-xl and above */
  --leading-snug: 1.35;     /* Subheadings, card titles */
  --leading-normal: 1.5;    /* Body text, descriptions */
  --leading-relaxed: 1.625; /* Long-form content, articles */
}

Font Weights

:root {
  --font-normal: 400;       /* Body, descriptions, table cells */
  --font-medium: 500;       /* Labels, nav items, button text, subtle emphasis */
  --font-semibold: 600;     /* Section headings, important numbers */
  --font-bold: 700;         /* Page-level titles ONLY — use sparingly */
}

Typography Rules

• App UI base font: 14px on body. Content/reading pages: 16px.
• Left-align everything. Never center body text. Center only hero headings on landing pages.
• Default heading weight: 600 (semibold). Use 700 only for the single page-level title (h1).
• One heading size per section. Use weight for sub-hierarchy, not stacked sizes.
• Secondary text uses --text-tertiary (slate-400), never a lighter tint of the accent blue.
• Letter-spacing: -0.011em on text-xl and above (tightens large text). 0 on body text. +0.025em on uppercase labels only.

---

Spacing

Scale — 4px base unit

:root {
  --space-0: 0;
  --space-0.5: 0.125rem;    /* 2px — hairline gaps, icon optical adjust */
  --space-1: 0.25rem;       /* 4px — icon-to-text gap, inline padding */
  --space-1.5: 0.375rem;    /* 6px — label-to-input gap */
  --space-2: 0.5rem;        /* 8px — tight spacing, button group gap */
  --space-3: 0.75rem;       /* 12px — list item padding, input padding-x */
  --space-4: 1rem;          /* 16px — card grid gap, section inner gap */
  --space-5: 1.25rem;       /* 20px — form field vertical gap */
  --space-6: 1.5rem;        /* 24px — card content padding */
  --space-8: 2rem;          /* 32px — section spacing */
  --space-10: 2.5rem;       /* 40px — major section gap */
  --space-12: 3rem;         /* 48px — page section padding */
  --space-16: 4rem;         /* 64px — landing page section padding only */
}

Spacing Application

| Element | Value | Token | |---------|-------|-------| | Card inner padding | 24px | --space-6 | | Card grid gap | 16px | --space-4 | | Form field vertical gap | 20px | --space-5 | | Label to input gap | 6px | --space-1.5 | | Input to helper/error text | 4px | --space-1 | | Button group gap | 8px | --space-2 | | Section vertical spacing | 32px | --space-8 | | Major section gap | 48px | --space-12 | | Page horizontal padding (mobile) | 16px | --space-4 | | Page horizontal padding (desktop) | 32-48px | --space-8 to --space-12 | | Sidebar item vertical padding | 6px | --space-1.5 | | Table cell padding | 10px 12px | --space-2.5 / --space-3 |

Spacing Rules

• Never exceed 64px spacing in app UI. Large spacing is for landing pages only.
• Use optical alignment, not mathematical. If a heading visually appears uncentered in a card despite equal padding, add 1-2px to the top to compensate for descenders.
• Gap between a heading and its first content paragraph: 8px. Not 16px (too much), not 4px (too tight).

---

Border Radius

:root {
  --radius-sm: 4px;         /* Badges, tags, small chips */
  --radius-md: 6px;         /* Buttons, inputs, dropdowns */
  --radius-lg: 8px;         /* Cards, panels */
  --radius-xl: 12px;        /* Modals, dialogs, popovers */
  --radius-full: 9999px;    /* Avatars, circular indicators ONLY */
}

Radius Rules

• Buttons: 6px. Not pill (9999px), not square (0).
• Inputs: 6px. Matches buttons — they sit together in forms.
• Cards: 8px. Slightly larger than elements inside.
• Modals: 12px. Maximum for rectangular elements.
• NEVER use border-radius above 12px on any rectangular element.
• radius-full (9999px) ONLY for avatars and circular status dots.

---

Shadows

:root {
  --shadow-xs: 0 1px 2px 0 rgba(15, 23, 42, 0.04);
  --shadow-sm: 0 1px 3px 0 rgba(15, 23, 42, 0.06),
               0 1px 2px -1px rgba(15, 23, 42, 0.06);
  --shadow-md: 0 4px 6px -1px rgba(15, 23, 42, 0.07),
               0 2px 4px -2px rgba(15, 23, 42, 0.05);
  --shadow-lg: 0 10px 15px -3px rgba(15, 23, 42, 0.08),
               0 4px 6px -4px rgba(15, 23, 42, 0.05);
  --shadow-xl: 0 20px 25px -5px rgba(15, 23, 42, 0.1),
               0 8px 10px -6px rgba(15, 23, 42, 0.06);
}

Shadow color uses Slate-900 (rgba(15, 23, 42)) instead of pure black. This creates warmer, more natural shadows that match the cool-toned gray system.

Shadow Rules

• Cards on white background: NO shadow. Use 1px border (--border-primary).
• Cards on gray background: --shadow-xs only.
• Dropdowns and popovers: --shadow-md to --shadow-lg.
• Modals and dialogs: --shadow-xl.
• Buttons: NEVER have shadows.
• Colored shadows (blue glow, etc.): NEVER.

---

Z-Index System

:root {
  --z-base: 0;
  --z-dropdown: 100;
  --z-sticky: 200;
  --z-overlay: 300;
  --z-modal: 400;
  --z-popover: 500;
  --z-tooltip: 600;
  --z-toast: 700;
}

Z-Index Rules

• NEVER use arbitrary z-index values (z-index: 9999).
• Every floating element uses one of these 8 layers.
• Stacking within a layer: use z-index: calc(var(--z-dropdown) + 1) for sub-layers.
• Toast notifications sit above everything except tooltips.

---

Buttons

Variants

/* Primary */
.btn-primary {
  background: var(--accent-primary);
  color: var(--text-on-accent);
  border: 1px solid transparent;
  padding: 7px 15px;
  font-size: var(--text-sm);
  font-weight: var(--font-medium);
  border-radius: var(--radius-md);
  line-height: 20px;
  height: 36px;
  cursor: pointer;
  transition: background var(--transition-normal);
}

.btn-primary:hover {
  background: var(--accent-primary-hover);
}

.btn-primary:active {
  background: var(--accent-primary-active);
}

.btn-primary:focus-visible {
  outline: 2px solid var(--accent-primary);
  outline-offset: 2px;
}

.btn-primary:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

/* Secondary (outlined) */
.btn-secondary {
  background: var(--bg-primary);
  color: var(--text-primary);
  border: 1px solid var(--border-secondary);
}

.btn-secondary:hover {
  background: var(--bg-secondary);
}

/* Ghost (no border) */
.btn-ghost {
  background: transparent;
  color: var(--text-secondary);
  border: 1px solid transparent;
}

.btn-ghost:hover {
  background: var(--bg-secondary);
  color: var(--text-primary);
}

/* Danger */
.btn-danger {
  background: var(--status-error);
  color: var(--text-on-accent);
  border: 1px solid transparent;
}

.btn-danger:hover {
  background: #B91C1C;
}

Button Sizes

| Size | Height | Padding | Font Size | Usage | |------|--------|---------|-----------|-------| | Small | 28px | 3px 11px | 12px | Dense UIs, table row actions | | Medium | 36px | 7px 15px | 14px | DEFAULT — forms, toolbars | | Large | 44px | 11px 23px | 16px | Landing page CTAs only |

Button Rules

• Default to Medium (36px). Small for dense UIs. Large for landing pages only.
• Text is sentence case ("Save changes"). Not Title Case. Not ALL CAPS.
• Maximum 2 buttons in a group (primary + secondary). Third action becomes a text link or menu.
• Icon buttons: square (36x36 medium), icon 16-20px centered.
• Loading state: replace text with spinner, maintain button width to prevent layout shift.
• Padding uses odd values (7px, 15px) because the 1px border means total height = 7+7+20+1+1 = 36px exactly.

---

Inputs & Forms

.input {
  height: 36px;
  padding: 7px 11px;
  font-size: var(--text-sm);
  font-family: inherit;
  color: var(--text-primary);
  background: var(--bg-primary);
  border: 1px solid var(--border-secondary);
  border-radius: var(--radius-md);
  transition: bo

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vmvenkatesh78](https://github.com/vmvenkatesh78)
- **Source:** [vmvenkatesh78/engineering-skills](https://github.com/vmvenkatesh78/engineering-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.