Swiss Knife UI Skill

This note stores the reusable UI skill distilled from the eight YouTube videos provided on 2026-07-05. Raw captions were fetched for analysis, but full transcripts are not stored here. This is a paraphrased synthesis and working skill.

Source Videos

Local Codex Skill

Created locally at:

/home/code/.codex/skills/swiss-knife-ui

Validated with:

quick_validate.py /home/code/.codex/skills/swiss-knife-ui

Skill Frontmatter

name: swiss-knife-ui
description: Build or refactor polished, functional frontend UIs using a practical design system checklist. Use when Codex is asked to improve app UI, create dashboards, client portals, SaaS tools, landing pages, responsive layouts, typography, color systems, hierarchy, interaction states, or make an interface feel more professional and usable.

Skill Body

Use this skill to turn vague UI requests into a shippable interface. Prefer a functional product surface over a decorative landing page unless the user explicitly asks for marketing.

Workflow

1. Identify the product type: operational app, dashboard, client portal, marketing page, checkout, editor, game, or internal tool.
2. Define the primary user job and the first-screen workflow. Do not start with hero copy for an app.
3. Choose the navigation model:

• Sidebar for serious multi-module apps, dashboards, compliance, admin, CRM, or operator workflows.
• Top nav for small public sites, simple tools, or content-heavy pages.
• Tabs for sibling views inside one module.

1. Build layout before decoration: page shell, navigation, toolbar, content regions, empty states, dense lists, forms, tables, dialogs.
2. Apply the UI checks below.
3. Verify responsive behavior and text fit. Make the mobile flow usable, not merely compressed.
4. Run the project build or equivalent validation.

Strong Defaults

• Use real product functionality on the first screen.
• Use sidebars for serious tools with more than four modules.
• Use cards only for repeated objects, panels, modals, or framed tools.
• Give every interactive element a visible state: default, hover, focus, active, disabled, loading where relevant.
• Prefer explicit labels over clever copy.
• Use a restrained color system with semantic status colors.
• Use type scale, spacing, borders, contrast, and alignment before shadows or decorative effects.
• Keep calculations, compliance logic, and final numbers outside decorative UI code unless the repo already has no better layer.

UI Heuristics

Product First

Design from the user job. Before styling, answer:

• Who is using this screen?
• What decision or action must happen first?
• What information must stay visible while they act?
• What can be hidden behind secondary navigation?
• What is the failure state, empty state, and completed state?

If the app is operational, start with the workspace. Landing pages are for acquisition, not the core product.

Layout

Use layout primitives intentionally:

• Use CSS grid for page regions, dashboards, tables of panels, and fixed two-axis layouts.
• Use flexbox for toolbars, inline controls, button rows, chips, and wrapping groups.
• Set min widths, max widths, and stable dimensions for controls that should not jump.
• Use minmax(0, 1fr) in grid columns containing text or tables.
• Wrap before overflow. Use horizontal scroll only for real data tables.
• Align by edges. Random center alignment makes serious tools feel amateur.

Navigation

Pick navigation based on information architecture:

• Sidebar: multi-module app, admin, CRM, compliance, document workflow, project workspace.
• Top nav: public site, small tool, simple content site.
• Tabs: alternate views of the same object.
• Breadcrumbs: nested records or detail pages.

A serious app should usually keep context visible: current account, case, project, status, and next action.

Hierarchy

Make the scan path obvious:

• One primary action per region.
• Use section titles that name the object or job, not generic marketing phrases.
• Group related fields and actions.
• Push metadata into secondary text, badges, or side panels.
• Use status badges for state, not decoration.
• Keep the most important number or decision near the control that changes it.

Typography

Typography does most of the polish work:

• Use a small scale with clear jumps: body, label, section title, page title.
• Do not use giant hero type inside panels or dense app screens.
• Use font weight to create hierarchy before adding color.
• Use muted text for secondary details, but keep contrast readable.
• Keep line length controlled for prose.
• Avoid negative letter spacing.
• Do not scale font size directly with viewport width.

Color

Build a palette instead of choosing colors ad hoc:

• Background: quiet page color.
• Panel: white or near-white surface.
• Ink: primary text.
• Muted: secondary text.
• Line: borders and dividers.
• Brand: primary action and active nav.
• Semantic: good, warning, bad, neutral.

Use lightness and saturation deliberately. Most UI should be neutral, with color reserved for navigation, state, and decisions. Avoid making the entire interface one hue family.

Depth

Use depth to separate layers, not to decorate everything:

• Borders are the default separator for app UI.
• Use shadows for floating elements, active panels, modals, and important surfaces.
• Keep shadow blur and opacity subtle.
• Do not nest cards inside cards unless there is a real object hierarchy.
• Add depth after spacing and hierarchy are already correct.

Components

Create repeatable components for repeated objects:

• Navigation item
• Toolbar button
• Status badge
• Data card
• Finding row
• Document row
• Form field group
• Empty state
• Table row
• Modal or drawer

Components should encode behavior and state, not just styling.

Interaction

A usable UI needs operational states:

• Hover state for clickable surfaces.
• Focus state for keyboard navigation.
• Active state for selected navigation.
• Disabled state when actions cannot run.
• Loading state when an action takes time.
• Empty state that tells the next action.
• Error state that says what failed and how to recover.

Do not make a button if it cannot plausibly do something in the product model. In a mockup, label future actions clearly.

Responsive Behavior

Responsive design is not shrinking everything:

• Collapse sidebars into top or stacked navigation on small screens.
• Keep forms one column on mobile.
• Keep tables scrollable with fixed column meaning.
• Prioritize the next action, status, and record identity.
• Avoid tiny touch targets.
• Test long text and long words.

Reference-Driven Design

Originality is less important than useful execution. Before designing:

• Identify two or three real products in the same category.
• Borrow layout patterns, not branding.
• Combine proven patterns with the domain-specific workflow.
• Improve clarity, density, and trust rather than chasing novelty.

Final Quality Gate

Before finishing a UI task, check:

• Does the first screen perform the real product job?
• Is navigation appropriate for the number of modules?
• Is the primary action obvious?
• Are states represented?
• Does the text fit on mobile and desktop?
• Are colors semantic and restrained?
• Is typography doing hierarchy work?
• Are there unnecessary decorative cards, gradients, or vague hero sections?
• Did the build or preview verification pass?