Use when creating or modifying UI layouts, implementing responsive design, adding panels/split-views, styling components, or when agents jam multiple features into cramped interfaces. Covers 8-bit design compliance, transparency violations, rounded corner violations, and mobile UX.
Prevent "jammed UI," z-index conflicts, nested layout bugs, and 8-bit design violations through strict layout architecture rules.
The core problems agents create:
This contract enforces Flat Hierarchy + 8-bit Aesthetic with explicit pane caps, tokenized z-index scales, solid colors, and squared corners.
Is this UI/layout/styling work?
├── Yes → Follow this contract
└── No → Not applicable
Symptoms that signal this skill applies:
Layout Issues:
z-[100], z-[9999] appearingisOpen, width) drilled through componentsreact-resizable-panels causing flex height issues8-bit Design Violations:
/60, /80, /50 opacity modifiers)rounded-lg (6px), rounded-xl (12px)backdrop-blur, blur-[100px])HARD LIMIT: Maximum 3 parallel columns on desktop.
CORRECT (3 columns max):
[ Sidebar (Left) ] -- [ Main Surface (Center) ] -- [ Assistant (Right) ]
FORBIDDEN (nested split):
[ Sidebar ] -- [ Main --split--> [Sub1][Sub2] ] -- [ Assistant ]
Sub-features need space? Use Tabs, Drawers, or Modals. Never split the pane further.
| Breakpoint | Width | Max Columns | Layout Pattern |
|---|---|---|---|
| Mobile | <640px | 1 column | Bottom Tab Bar switches contexts |
| Tablet | 640-1024px | 2 columns | Left sidebar → Icon Rail, Show Main + Assistant |
| Desktop | ≥1024px | 3 columns | 20% / Flex-1 / 30% with min-widths |
Zero feature loss: Every desktop feature must map to a mobile affordance (tab/drawer/modal).
Stop using arbitrary values. Only this scale:
| Token | Value | Use For |
|---|---|---|
z-0 | 0 | Base canvas (Editor, text, standard panels) |
z-10 | 10 | Sticky headers/footers within panels |
z-20 | 20 | Floating Action Buttons, Badges |
z-30 | 30 | Drawers, Slide-overs |
z-40 | 40 | Global Command Palette, Dialogs |
z-50 | 50 | Modals, Toasts, Critical Alerts |
All overlays (dropdowns, tooltips, popovers) MUST render in a single OverlayRoot portal to avoid clipping.
The project uses an 8-bit retro design system. Violating this breaks the visual identity.
FORBIDDEN: Opacity modifiers on interactive elements
// ❌ WRONG - Transparency violations
className="bg-slate-800/60 hover:bg-slate-700/80"
className="bg-slate-900/50"
className="bg-slate-900/95"
className="bg-slate-800/40"
// ✅ CORRECT - Solid colors
className="bg-card hover:bg-secondary"
className="bg-background"
className="bg-[var(--card)]"
className="bg-[var(--secondary)]"
Why: Semi-transparent backgrounds cause text bleeding, contrast violations, and "horrible" layered UI. User feedback: "Those agent or configuration dropdowns with transparency and layers on top of another text... it is just horrible."
FORBIDDEN: Large rounded corners
// ❌ WRONG - Too round
className="rounded-lg" // 6px - TOclassName="rounded-xl" // 12pxO ROUND
- VERY TOO ROUND
className="rounded-2xl" // 16px - WHY
// ✅ CORRECT - 8-bit style
className="rounded-none" // Preferred for cards/panels
className="rounded-[4px]" // Max allowed (radius-md)
className="rounded-sm" // 2px (radius-sm)
Design token limits:
--radius: 0rem - Default: Squared corners--radius-sm: 0.125rem - 2px--radius-md: 0.25rem - 4px - MAX ALLOWEDFORBIDDEN: Blur on any element
// ❌ WRONG - Blur violations
className="blur-[100px]"
className="backdrop-blur"
className="backdrop-blur-md"
// ✅ CORRECT - 8-bit alternatives
// Option 1: Solid gradient
className="bg-gradient-to-br from-primary/30 to-transparent"
// Option 2: Pixelated glow effect
className="shadow-[0_0_40px_20px_rgba(249,115,22,0.3)]"
// Option 3: Remove entirely
{/* Decorative element removed per 8-bit design */}
/* ✅ CORRECT - Hard drop shadows */
--shadow-pixel: 2px 2px 0px 0px rgba(0, 0, 0, 0.5);
--shadow-pixel-primary: 2px 2px 0px 0px #c2410c;
--shadow-pixel-sm: 1px 1px 0px 0px rgba(0, 0, 0, 0.5);
/* ❌ WRONG - Soft shadows */
box-shadow: 0 4px 12px rgba(0,0,0,0.15);
box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
/* ✅ CORRECT - Snappy, 8-bit style */