SKILL.md

minimal-ui-design-system

Build minimal UI for Next.js, React, Svelte, and Vite. Use verified Hugeicons, Geist, simple colors, soft borders, clear spacing, and ample breathing room so no component competes for attention. Maintain enterprise-grade UX with an ultra-clean design. Avoid decorative styling. Keep the design clean, consistent, and easy to use.

risk
safe
source
trysapphire.today
date added
2026-03-27

Minimal UI Design System

This skill governs UI and design generation for minimal, clean, production-grade interfaces.

It is not a persona. It is not roleplay. It is a strict execution standard.

The goal is simple:

  • Build minimal interfaces that feel intentional
  • Keep the visual system clean, modern, and calm
  • Remove decorative noise
  • Preserve usability, hierarchy, and production quality
  • Eliminate ambiguity before implementation

1. Mandatory Preflight

Before generating visual UI code, resolve these two design decisions first unless the user already specified them:

Required Question 1 — Neutral Palette

Ask which neutral family the user wants for the design system:

  • zinc
  • neutral
  • stone
  • slate

Do not assume this. Do not mix multiple neutral families in one design.

Required Question 2 — Primary Accent

Ask which primary accent color the user wants for interactive emphasis.

This primary color may be used for:

  • primary buttons
  • active navigation states
  • links
  • focus accents
  • selected states
  • data emphasis

Do not use multiple primary accents unless the user explicitly requests that.

Default Fallback Rule

If the user does not specify either value and the task requires immediate output, use:

  • Neutral family: zinc
  • Primary accent: one restrained modern hue only

Do not introduce gradients. Do not introduce rainbow accents. Do not invent multiple brand colors.

2. Core Design Laws

These rules are mandatory.

Always

  • Design for minimalism, clarity, and production quality
  • Use restrained visual hierarchy
  • Use clean spacing and calm surfaces
  • Keep borders subtle and non-harsh
  • Keep typography sharp and readable
  • Use one neutral palette consistently
  • Use one primary accent consistently
  • Prefer simple composition over decorative styling

Never

  • Never use shadows
  • Never use gradients
  • Never use glow effects
  • Never use glassmorphism
  • Never use decorative blur as styling
  • Never use random icon libraries
  • Never guess icon names
  • Never add visual noise to “make it feel modern”
  • Never confuse minimal with empty or monochrome

Minimal does not mean black and white only.

A valid minimal palette may be:

  • one neutral family for structure
  • one primary accent for emphasis
  • black or near-black for strongest text
  • white or near-white for base surfaces

That is allowed. That is preferred. Gradient-heavy “AI slop” styling is not allowed.

Guardrails

Do not generate generic AI-slop. Do not default to safe SaaS patterns, trendy gradients, fake luxury clichés, bloated layouts, or decorative noise. Create a design with a clear point of view, one memorable idea, and real visual intent. Use generous breathing room, but do not confuse whitespace with weak design or inflated layout. Keep everything minimal, sharp, and deliberate.

Minimal means ruthless restraint, strong hierarchy, precise spacing, excellent typography, and zero unnecessary elements. Do not bloat titles, descriptions, cards, sections, or navigation. For website hero sections, keep the main heading to a maximum of 5 to 6 words and the supporting description to a maximum of 15 to 17 words. For cards and supporting sections, keep copy equally restrained: short title, short supporting text, no filler.

Emphasize the headline more than the description. Most users scan; they do not read bloated paragraphs. Write only what strengthens the interface. Every color, type choice, image treatment, and layout decision must feel intentional, distinctive, and specific to the product. If any section looks templated, predictable, bloated, or replaceable with a hundred other AI outputs, redesign it until it has identity.

3. Icon Standard — Hugeicons Only

Hugeicons is the canonical icon source.

Use Hugeicons only unless the user explicitly requests another icon system.

Strict Rules

  • Always verify icon availability before using an icon
  • Never hallucinate icon names
  • Never import icons blindly from old package paths
  • Never mix Hugeicons with Lucide, Heroicons, Tabler, or others unless explicitly requested

Discovery Procedure

Free library discovery command:

node -e "import('@hugeicons/core-free-icons').then(m=>console.log(Object.keys(m).join('\n')))"

If using a Pro style, replace the package name accordingly, for example:

  • @hugeicons-pro/core-solid-rounded

Installation

Install both the renderer and the icon pack:

npm install @hugeicons/react @hugeicons/core-free-icons

or

pnpm add @hugeicons/react @hugeicons/core-free-icons

Required Usage Pattern

Use the wrapper + icon data pattern.

import { HugeiconsIcon } from "@hugeicons/react";
import { DashboardSquare01Icon } from "@hugeicons/core-free-icons";

<HugeiconsIcon icon={DashboardSquare01Icon} size={24} color="currentColor" />

Icon Rules

  • Use HugeiconsIcon for rendering
  • Use verified icon data imports from the core package
  • Keep icon size proportional to surrounding typography
  • Use currentColor by default
  • Icon-only controls must have accessible labels
  • Do not oversize icons to compensate for weak layout
  • Do not use icons decoratively unless they support hierarchy or usability

4. Typography Standard — Geist by Default

Geist is the default font system.

Use Geist first. Do not default to Inter. Do not mix multiple sans families by default.

Install

bun add geist

Allowed Font Roles

  • GeistSans for UI text
  • GeistMono for code, data, technical values
  • GeistPixel* only if the user explicitly requests a pixel-display aesthetic

Pixel variants are not the default body font.

Minimal Root Layout Example

Keep the implementation minimal.

import "./globals.css";
import { GeistSans } from "geist/font/sans";
import { GeistMono } from "geist/font/mono";
import { cn } from "@/lib/utils";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html
      lang="en"
      className={cn("h-full antialiased", GeistSans.variable, GeistMono.variable)}
    >
      <body className="min-h-full font-sans tracking-normal">
        {children}
      </body>
    </html>
  );
}

Typography Rules

Always use:

  • antialiased
  • tracking-normal or tracking-tight

Never use:

  • tracking-wide
  • exaggerated letter spacing
  • decorative font mixing
  • random display fonts

Weight Rules

Default weights:

  • font-normal
  • font-medium only when necessary for hierarchy

Avoid:

  • font-semibold
  • font-bold

Use stronger weights only if the user explicitly asks for stronger emphasis.

Hierarchy Rules

Typography must feel calm and precise.

Preferred pattern:

  • page title: restrained, clean, not oversized
  • section title: one step below page title
  • card title: compact and readable
  • body: clear and low-friction
  • helper text: lighter emphasis, never noisy
  • code/data: font-mono

Numeric Data

Use tabular figures for metrics, prices, counts, and aligned technical values.

5. Color System

The selected neutral family controls the structural palette.

Apply it consistently to:

  • text hierarchy
  • borders
  • dividers
  • muted surfaces
  • table headers
  • input chrome
  • layout framing

Structural Palette Rules

Use the chosen neutral family for:

  • primary text
  • secondary text
  • tertiary text
  • borders
  • dividers
  • muted backgrounds
  • inactive controls

Do not mix stone with zinc, or slate with neutral, inside one system unless explicitly instructed.

Primary Accent Rules

The primary accent may be used for:

  • CTA buttons
  • active tabs
  • selected states
  • links
  • focused controls
  • progress/data emphasis

Do not use the primary accent for:

  • large page backgrounds
  • card backgrounds by default
  • decorative gradients
  • purely ornamental glow or branding clutter

Minimal Color Principle

Minimal does not mean monochrome. It means restrained color allocation.

Valid:

  • neutral system + one primary accent
  • black/near-black + neutral system + one primary accent
  • white/near-white + neutral system + one primary accent

Invalid:

  • gradients
  • multiple competing accents
  • neon decoration
  • colored shadows
  • arbitrary colorful surfaces

6. Surface, Border, and Radius Rules

Shadows

No shadows. None.

Do not use:

  • shadow-*
  • drop-shadow-*
  • glowing rings as decoration
  • fake depth through blur and bloom

Borders

Borders must be soft, subtle, and non-harsh.

Preferred border behavior:

  • light neutral border
  • slightly stronger on hover
  • calm focus state
  • visible enough for structure, never heavy

Do not use:

  • black borders by default
  • thick outlines
  • harsh contrast borders
  • double-border styling for decoration

Radius

Use restrained radius. Preferred values:

  • rounded-lg
  • rounded-xl for larger containers only

Do not use:

  • sharp corners by default
  • pill shapes everywhere
  • oversized radius on every component

7. Layout and Spacing Rules

Minimal UI fails when spacing is cramped.

Always

  • give sections breathing room
  • separate content groups clearly
  • keep containers readable
  • preserve rhythm across vertical stacks
  • use clean max-width constraints
  • avoid edge-to-edge layout unless explicitly requested

Never

  • cram content into dense cards
  • stack unrelated controls tightly
  • create fake complexity with too many nested wrappers
  • fill every empty area just because space exists

Layout Pattern

Default page structure:

  1. header
  2. supporting text if needed
  3. content sections
  4. action area

Use spacing to define hierarchy before using color.

8. Component Rules

Buttons

Buttons must:

  • have clear visual priority
  • use the chosen primary accent or a neutral treatment
  • include hover and active states
  • have disabled styling
  • preserve readable text contrast
  • avoid over-rounded “pill for everything” styling

Primary buttons should feel deliberate, not loud.

Inputs

Inputs must:

  • use subtle neutral borders
  • use calm focus indication
  • avoid harsh outlines
  • keep background clean
  • preserve strong readability
  • feel soft, not decorative

Cards

Cards must:

  • use subtle borders
  • have clean internal padding
  • avoid shadows
  • avoid loud filled backgrounds unless explicitly needed
  • separate header/content cleanly

Tables

Tables must:

  • have readable row spacing
  • use subtle dividers
  • keep headers restrained
  • support hover states only when interactive
  • avoid noisy zebra patterns unless needed for scanning

Dialogs / Drawers

Must:

  • be compact
  • be clearly framed
  • use subtle borders
  • preserve hierarchy through spacing
  • avoid theatrical styling

Navigation

Navigation must:

  • be visually obvious
  • distinguish active state clearly
  • not depend on color alone
  • use Hugeicons consistently
  • avoid oversized icons and oversized labels

9. Interaction Rules

Every interactive element must clearly look interactive.

Required:

  • hover state
  • active state
  • focus-visible state
  • disabled state
  • pointer cursor where appropriate

Do not leave clickable elements visually static.

Motion

Keep motion restrained.

Allowed:

  • fast, subtle transitions
  • opacity change
  • border-color change
  • background-color change
  • transform only when light and justified

Not allowed:

  • bouncy motion
  • decorative parallax
  • dramatic reveal animations
  • motion used to fake quality

10. Accessibility Rules

Accessibility is mandatory.

Required

  • sufficient contrast
  • visible keyboard focus
  • semantic HTML first
  • aria-label on icon-only controls
  • real button elements for buttons
  • real links for navigation
  • headings that reflect page hierarchy

Never

  • rely on color alone for state
  • use icons without accessible meaning
  • use div soup when semantic elements are correct

11. Implementation Rules

Technical Baseline

  • strict TypeScript only
  • no any
  • no unsafe shortcuts
  • production-ready structure
  • modern React patterns
  • modern Tailwind usage
  • minimal but complete implementation

Styling Rule

Every visual decision must be intentional.

Do not rely on component defaults and assume they look good. Style every important surface deliberately.

Design Resolution Rule

If the user’s request conflicts with this skill:

  1. follow explicit user instruction
  2. otherwise follow this skill
  3. do not silently invent a third direction

12. Output Contract

When generating UI work, return:

  1. code
  2. short implementation summary
  3. explicit checklist confirming all requested requirements were satisfied

Do not add filler. Do not add design philosophy paragraphs unless requested. Do not teach unless the user asks for explanation.

13. Hard Prohibitions

These are absolute unless the user explicitly overrides them.

  • No shadows
  • No gradients
  • No glow
  • No glassmorphism
  • No random icon library mixing
  • No unverified Hugeicons imports
  • No defaulting to Inter over Geist
  • No decorative font mixing
  • No tracking-wide by default
  • No harsh borders
  • No thick outlines
  • No bright decorative color systems
  • No fake “modern” styling tricks
  • No roleplay language
  • No persona framing
  • No unnecessary refactors outside the user request

14. Final Checklist

Before finalizing, verify all of the following:

Design Decisions

  • Neutral family is resolved: zinc, neutral, stone, or slate
  • Primary accent is resolved
  • No extra accent system was introduced

Icon System

  • Hugeicons used
  • Icon names were verified from the correct package
  • HugeiconsIcon wrapper used
  • Icon-only controls have labels

Typography

  • Geist is the default font system
  • antialiased is applied
  • tracking-normal or tracking-tight used
  • no tracking-wide by default
  • weight usage is restrained and consistent

Styling

  • no shadows
  • no gradients
  • no glow
  • borders are subtle
  • radius is restrained
  • spacing is clean

UX

  • hover states exist
  • focus states exist
  • disabled states exist
  • clickable items look clickable
  • accessibility basics are satisfied

Output

  • code is production-ready
  • summary is brief
  • checklist is explicit
  • no filler was added

15. Reference Snippets

Hugeicons Example

import { HugeiconsIcon } from "@hugeicons/react";
import {
  DashboardSquare01Icon,
  Settings02Icon,
  UserCircleIcon,
} from "@hugeicons/core-free-icons";

export function SidebarNavigation() {
  return (
    <nav className="flex flex-col gap-4">
      <div className="flex items-center gap-2">
        <HugeiconsIcon
          icon={DashboardSquare01Icon}
          size={24}
          color="currentColor"
        />
        <span>Dashboard</span>
      </div>

      <div className="flex items-center gap-2">
        <HugeiconsIcon
          icon={Settings02Icon}
          size={24}
          strokeWidth={2}
          color="currentColor"
        />
        <span>Settings</span>
      </div>

      <button aria-label="User Profile" type="button">
        <HugeiconsIcon icon={UserCircleIcon} size={28} />
      </button>
    </nav>
  );
}

Geist Import Reference

import { GeistSans } from "geist/font/sans";
import { GeistMono } from "geist/font/mono";
import {
  GeistPixelSquare,
  GeistPixelGrid,
  GeistPixelCircle,
  GeistPixelTriangle,
  GeistPixelLine,
} from "geist/font/pixel";

Use the pixel variants only when the user explicitly asks for a pixel-display treatment. They are not default UI body fonts.