stacks-design-minimalist

name	stacks-design-minimalist
description	Use when a Stacks UI should feel editorial and minimalist (Notion/Linear vibe) - designing a docs site, dashboard, landing page, or content surface that needs restrained warm monochrome, typographic contrast, flat bento grids, muted pastel accents, and no gradients or heavy shadows. Composes with stacks-design-taste as an aesthetic preset built on stx + Crosswind + composables.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Editorial / Minimalist UI (Stacks)

Related skills: refines stacks-design-taste (the flagship anti-slop skill) with a restrained editorial preset. Build with stacks-stx (templating, signals), stacks-crosswind (utilities, dark mode, custom rules), and stacks-ui (Craft + headless components). Full composable reference: stacks-composables.

1. Protocol Overview

Premium utilitarian minimalism and editorial UI. A frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms, built with stx + Crosswind. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.

2. Absolute Negative Constraints (Banned Elements)

Strictly avoid these generic web development defaults:

• DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces. (These are font choices; load your chosen fonts via the fonts config plus @font-face / <link> with font-display: swap, never next/font.)
• DO NOT use generic thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons". Use Iconify i-* classes instead, and NEVER hand-roll SVG icon paths or npm install an icon package.
• DO NOT use Crosswind's default heavy drop shadows (for example shadow-md, shadow-lg, shadow-xl). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
• DO NOT use primary colored backgrounds for large elements or sections (no bright blue, green, or red hero sections).
• DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
• DO NOT use rounded-full (pill shapes) for large containers, cards, or primary buttons.
• DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper Iconify icons or clean SVG primitives.
• DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
• DO NOT use AI copywriting cliches: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.

3. Typographic Architecture

The interface must rely on extreme typographic contrast and premium font selection for an editorial feel. Register these in the fonts config; load with @font-face + font-display: swap.

• Primary Sans-Serif (Body, UI, Buttons): clean, geometric, or system-native fonts with character. Target: font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif.
• Editorial Serif (Hero Headings & Quotes): Target: font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif. Apply tight tracking (letter-spacing: -0.02em to -0.04em) and tight line-height (1.1).
• Monospace (Code, Keystrokes, Meta-data): Target: font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace.
• Text Colors: Body text must never be absolute black (#000000). Use off-black/charcoal (#111111 or #2F3437) with a generous line-height of 1.6 for legibility. Secondary text should be muted gray (#787774).

4. Color Palette (Warm Monochrome + Spot Pastels)

Color is a scarce resource, used only for semantic meaning or subtle accents.

• Canvas / Background: Pure White #FFFFFF or Warm Bone/Off-White #F7F6F3 / #FBFBFA.
• Primary Surface (Cards): #FFFFFF or #F9F9F8.
• Structural Borders / Dividers: Ultra-light gray #EAEAEA or rgba(0,0,0,0.06).
• Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
  • Pale Red: #FDEBEC (Text: #9F2F2D)
  • Pale Blue: #E1F3FE (Text: #1F6C9F)
  • Pale Green: #EDF3EC (Text: #346538)
  • Pale Yellow: #FBF3DB (Text: #956400)

Expose these as Crosswind theme tokens or CSS custom properties in config/ui.ts so dark mode (dark: + useColorMode() / useDark()) stays consistent.

5. Component Specifications

• Bento Box Feature Grids:
  • Use asymmetrical CSS Grid layouts (grid grid-cols-1 md:grid-cols-6 with mixed col-span).
  • Cards must have exactly border: 1px solid #EAEAEA (border border-[#EAEAEA]).
  • Border-radius must be crisp: 8px or 12px maximum (rounded-lg / rounded-xl).
  • Internal padding must be generous (p-6 to p-10).
• Primary Call-To-Action (Buttons):
  • Solid background #111111, text #FFFFFF.
  • Slight border-radius (rounded to rounded-md). No box-shadow.
  • Hover state is a subtle color shift to #333333 or a micro active:scale-[0.98].
• Tags & Status Badges:
  • Pill-shaped (rounded-full), very small typography (text-xs), uppercase with wide tracking (tracking-[0.05em]).
  • Background uses the defined muted pastels. (Pills are allowed on small badges, never on large containers.)
• Accordions (FAQ):
  • Strip all container boxes. Separate items only with border-b border-[#EAEAEA].
  • Use a clean, sharp + and - toggle. Reach for the headless Disclosure component in stacks-ui and toggle state with a signal.
• Keystroke Micro-UIs:
  • Render shortcuts as physical keys using <kbd>: border border-[#EAEAEA] rounded bg-[#F7F6F3] in the monospace font.
• Faux-OS Window Chrome:
  • When mocking software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (macOS window controls).

<!-- resources/components/BentoCard.stx -->
<article class="p-8 bg-white dark:bg-neutral-900 border border-[#EAEAEA] rounded-xl">
  <span class="inline-block px-2 py-0.5 text-[#1F6C9F] text-xs tracking-[0.05em] uppercase bg-[#E1F3FE] rounded-full">Docs</span>
  <h3 class="mt-4 text-[#111111] text-2xl dark:text-neutral-100">Structured writing</h3>
  <p class="mt-2 leading-[1.6] text-[#787774]"><slot /></p>
</article>

6. Iconography & Imagery Directives

• System Icons: Use Iconify i-* classes with a technical, slightly thicker-stroke aesthetic (for example i-ph-* bold/fill weights, or i-radix-icons-*). Standardize stroke width across all icons; keep one collection per project. NEVER hand-roll SVG icon paths.
• Illustrations: Monochromatic, rough continuous-line ink sketches on white, featuring a single offset geometric shape filled with a muted pastel color.
• Photography: High-quality, desaturated, warm-toned images. Apply subtle overlays (opacity: 0.04 warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use <img> with explicit width/height (reserve space to avoid CLS) and the stx asset pipeline; heavy assets go through @stacksjs/storage. Placeholder: https://picsum.photos/seed/{context}/1200/800.
• Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (radial-gradient with warm tones at opacity: 0.03), or minimal geometric line patterns to add depth without breaking the clean aesthetic.

7. Subtle Motion & Micro-Animations

Motion should feel invisible: present but never distracting. Quiet sophistication, not spectacle. Stacks ships no animation library; build motion with Crosswind transitions, CSS keyframes in the .stx <style> block, and the allowed composables. Do NOT import motion, gsap, or framer-motion.

• Scroll Entry: Elements fade in gently as they enter the viewport. Use translateY(12px) + opacity: 0 resolving over 600ms with cubic-bezier(0.16, 1, 0.3, 1). Toggle the class with useIntersectionObserver(target, cb) or useElementVisibility(target); NEVER window.addEventListener('scroll', ...).
• Hover States: Cards lift with an ultra-subtle shadow shift (box-shadow from 0 0 0 to 0 2px 8px rgba(0,0,0,0.04) over 200ms). Buttons respond with active:scale-[0.98].
• Staggered Reveals: List and grid items enter with a cascade delay (animation-delay: calc(var(--index) * 80ms)). Never mount everything at once.
• Background Ambient Motion: Optional. A single very slow radial gradient blob (animation-duration: 20s+, opacity: 0.02-0.04) drifting behind hero sections, applied to a position: fixed; pointer-events: none layer. Never on scrolling containers.
• Performance: Animate exclusively via transform and opacity. No layout-triggering properties (top, left, width, height). Use will-change: transform sparingly and only on actively animating elements.
• Reduced motion: gate with CSS @media (prefers-reduced-motion: reduce) and/or useMediaQuery('(prefers-reduced-motion: reduce)').

<script client>
  const block = useRef('block')
  const shown = state(false)
  useIntersectionObserver(block, (e) => { if (e[0].isIntersecting) shown.set(true) }, { threshold: 0.2 })
</script>

<section ref="block"
         :class="shown() ? 'translate-y-0 opacity-100' : 'translate-y-3 opacity-0'"
         class="duration-[600ms] ease-[cubic-bezier(0.16,1,0.3,1)] transition-all">
  <slot />
</section>

8. Execution Protocol

When writing stx / Crosswind or designing a layout:

1. Establish macro-whitespace first. Use massive vertical padding between sections (py-24 or py-32).
2. Constrain main typography content width to max-w-4xl or max-w-5xl.
3. Apply the custom typographic hierarchy and monochromatic color tokens immediately.
4. Ensure every card, divider, and border adheres strictly to the 1px solid #EAEAEA rule.
5. Add scroll-entry animations to all major content blocks via useIntersectionObserver.
6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures; no empty flat backgrounds.
7. Deliver complete stx that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments. Ship the full file, never a skeleton or placeholder comment.