saccoai-frontend-design

This skill produces a creative design direction for any frontend project. It transforms extracted design tokens and site analysis into a distinctive visual identity — typography choices, color strategy, spatial composition, motion narrative, and a signature element that makes the project unforgettable.

The user provides: a project context (URL, description, or brief), and optionally a mood or aesthetic preference. When running inside the saccoai pipeline, it reads .saccoai/design-system/ and .saccoai/analysis/ automatically.

Why This Exists

AI-built frontends converge on the same look: Inter font, purple-to-blue gradient, white background, evenly-spaced card grids, predictable hero sections. This happens because models default to statistically common patterns. Every project built with saccoai skills should look like it was designed for that specific client by someone who cares about craft. This skill is the mechanism that ensures that.

The goal is not maximalism for its own sake. A minimal site can be just as distinctive as an elaborate one — what matters is intentionality. Every typographic choice, color relationship, and spatial decision should have a reason.

Design Thinking Process

Before writing any code or selecting any component, work through these five questions. Write the answers into the design brief.

Q1: What is the emotional territory?

Not "what industry" — that produces formulaic output. Instead: what should someone feel when they land on this site?

Examples of emotional territories (combine 2-3):

• Authority + warmth (a law firm that doesn't feel cold)
• Precision + playfulness (a fintech that doesn't feel corporate)
• Calm + confidence (a wellness brand that doesn't feel flimsy)
• Energy + sophistication (a creative agency that doesn't feel chaotic)
• Trust + modernity (a government service that doesn't feel stuck in 2005)

The emotional territory drives every downstream decision. Two law firms might share an industry but inhabit completely different emotional territories.

Q2: What is the visual anchor?

Every memorable site has one element you notice first. Decide what it is:

• Typography-led: The typeface IS the design. Large, distinctive type carries the entire visual identity. Layout is simple to let the type breathe.
• Color-led: A bold or unusual color relationship defines the site. Maybe a single saturated accent on near-monochrome. Maybe an unexpected warm/cool tension.
• Composition-led: The layout itself is the statement. Asymmetry, overlap, diagonal flow, or dramatic negative space.
• Texture-led: Surface and atmosphere define the mood. Grain, noise, mesh gradients, layered transparencies, or tactile materials.
• Motion-led: Movement tells the story. Scroll-driven reveals, page transitions, or a single choreographed entrance sequence.

Pick one anchor. The others support it but don't compete.

Q3: What is the signature element?

One specific, concrete design choice that someone would remember after closing the tab:

• A particular way headings split across two lines with different weights
• An unusual scrolling behavior on the hero section
• A color that shifts subtly on hover across the entire page
• Navigation that transforms as you scroll
• A grid that intentionally breaks in one section
• An image treatment (duotone, cutout, masked shape) used consistently
• A custom cursor or selection color that reinforces the brand

This is not optional. Every project gets one. Write it into the design brief.

Q4: What does "too far" look like?

Define the constraint boundary. For a corporate site, "too far" might be animated text that obscures readability. For a creative portfolio, "too far" might be so much motion that performance suffers. Knowing the limit prevents both timidity and excess.

Q5: What would make this generic?

List the 3 most likely ways this project could end up looking like every other AI-built site. Then actively avoid them. Common traps:

• Default shadcn/ui gray palette with no personality
• Geist for everything (it's a great font — but using it without a distinctive display partner is lazy)
• Hero → three-column features → testimonials → CTA (the "startup template" layout)
• Uniform card grids with identical border-radius and shadow
• Purple/blue gradient accents on white

Creative Direction Framework

Typography as Identity

Typography is the single highest-leverage design decision. Two sites with identical layouts but different type feel completely different.

The pairing principle: Every project needs a display font and a body font that create tension. Same-family or same-vibe pairings (two geometric sans-serifs) feel bland. Look for productive contrast:

Display Character	Pairs Well With	Creates
High-contrast serif (Playfair, Cormorant)	Clean geometric sans (DM Sans, Outfit)	Elegant authority
Chunky slab (Roboto Slab, Zilla Slab)	Humanist sans (Source Sans 3, Noto Sans)	Grounded warmth
Geometric display (Cabinet Grotesk, Clash Display)	Neutral body (IBM Plex Sans, Atkinson Hyperlegible)	Modern edge
Handwritten/script (Caveat, Kalam)	Precise sans (Inter, Geist)	Personal + professional
Monospace display (JetBrains Mono, Fira Code)	Rounded sans (Nunito, Rubik)	Technical + approachable
Wide/extended (Syne, Unbounded)	Condensed body (Barlow Condensed, Oswald)	Dramatic scale contrast

Rules:

• Never use the same font for both display and body
• Never reuse a pairing from a previous saccoai project
• Test at h1 (48-72px), h3 (24-32px), and body (16px) before committing
• Load via next/font — maximum 2 families, prefer variable fonts
• Write the rationale into the design brief: why this pairing, what tension it creates

Color Strategy

Extracted tokens from .saccoai/design-system/ are a starting point, not a destination. The design brief should define how to interpret the palette:

Amplification: Take the client's existing accent color and make it braver. If they had a muted blue, consider whether a deeper, more saturated version serves the emotional territory better.

Reduction: Most extracted palettes have too many colors. Pick a dominant, a secondary, and an accent. Let everything else be neutral. Three colors used with conviction beat eight colors used timidly.

Temperature: Decide if the palette leans warm or cool, and commit. Mixed-temperature palettes without intention feel accidental. A warm neutral base (stone, sand, cream) with a cool accent (teal, slate blue) creates intentional tension.

The dark mode question: Dark mode is not "invert the colors." It requires its own color relationships. Reduce contrast slightly (not pure white on pure black), shift accents to be more luminous, and reconsider which color is dominant.

Write into the design brief:

• Primary, secondary, accent as specific hex values
• Dark mode variants
• How the accent is used (sparingly for CTAs only? As a highlight throughout? As a hover state?)
• What color is explicitly not used and why

Spatial Composition

Layout is not just "put things in a grid." See references/visual-techniques.md for specific patterns, but the design brief should declare the spatial strategy:

Rhythm: Will sections have uniform spacing (calm, predictable) or varied spacing (dynamic, editorial)? Uniform works for corporate/trust. Varied works for creative/editorial.

Density: Will the page breathe (generous whitespace, floating content) or pack information efficiently (dashboard-like)? Match to the content type and audience.

Symmetry: Symmetric layouts feel stable and trustworthy. Asymmetric layouts feel dynamic and modern. The brief should declare which, and where exceptions happen.

The break: Every layout needs at least one moment where the established pattern changes. A full-bleed image in a contained layout. A single-column section in a grid-heavy page. An oversized heading in a text-dense section. The break creates emphasis and prevents monotony.

Motion as Narrative

Motion should tell a story, not decorate. The design brief defines what story:

Entrance narrative: How does the page introduce itself? Options:

• Immediate: Content is there. No animation. Confidence. (Trust/minimal)
• Reveal: Content fades/slides in as a single orchestrated moment. (Refined/editorial)
• Staggered: Elements appear in sequence, drawing the eye through the hierarchy. (Technical/modern)
• Dramatic: A single bold animation (hero zoom, text split, image parallax) sets the tone. (Expressive/creative)

Scroll narrative: What happens as the user moves through the page?

• Static: Nothing. Content is read like a document. (Minimal/trust)
• Subtle reveals: Sections fade in when they enter the viewport. (Most sites)
• Progressive disclosure: Content builds as you scroll, with each section adding to the story. (Editorial/product)
• Scroll-linked: Elements move, scale, or transform based on scroll position. (Expressive — use sparingly)

Interaction narrative: What happens when the user engages?

• Hover states: lift, color shift, underline reveal, image zoom
• Click feedback: scale pulse, ripple, color flash
• Form focus: border animation, label float, validation slide

Write into the brief: Which narrative for each category, plus the one moment that gets the most motion investment. Usually the hero or the first section transition.

Visual Atmosphere

Background and surface treatment create mood. See references/visual-techniques.md for CSS implementations:

• Clean: Pure backgrounds, sharp edges, no texture. For precision-focused brands.
• Textured: Subtle grain, noise, or paper texture. For warmth and tactility.
• Gradient: Mesh gradients, radial gradients, or gradient borders. For energy and modernity.
• Layered: Overlapping planes, semi-transparent cards, depth via shadow. For sophistication.
• Dark atmospheric: Dark backgrounds with glowing accents, subtle grid lines, or particle effects. For tech/AI products.

Pick one primary atmosphere. Write it into the brief with specific implementation notes.

Output Format

When running inside the saccoai pipeline, produce a design brief at .saccoai/design-brief/design-brief.md:

# Design Brief: {project name}

## Emotional Territory
{2-3 combined emotions with rationale}

## Visual Anchor
{typography-led / color-led / composition-led / texture-led / motion-led}
{Why this anchor suits the project}

## Signature Element
{The one specific, concrete design choice}

## Constraint Boundary
{What "too far" looks like for this project}

## Generic Traps to Avoid
{3 specific ways this project could look like AI slop}

## Typography
- **Display**: {font name} — {why}
- **Body**: {font name} — {why}
- **Tension**: {what contrast the pairing creates}
- **Scale**: h1 {size}, h2 {size}, h3 {size}, body {size}, small {size}

## Color Strategy
- **Palette**: {primary hex}, {secondary hex}, {accent hex}, {neutrals}
- **Dark mode**: {adjusted values}
- **Accent usage**: {how and where}
- **Excluded**: {what color is NOT used and why}
- **Interpretation note**: {how this differs from extracted tokens and why}

## Spatial Composition
- **Rhythm**: {uniform / varied}
- **Density**: {breathing / efficient}
- **Symmetry**: {symmetric / asymmetric / mixed}
- **The break**: {where the pattern changes and how}
- **Max content width**: {value}
- **Section spacing**: {mobile / desktop}

## Motion Plan
- **Entrance**: {immediate / reveal / staggered / dramatic}
- **Scroll**: {static / subtle reveals / progressive / scroll-linked}
- **Interaction**: {hover + click + focus descriptions}
- **Hero moment**: {the one animation that gets the most investment}
- **Reduced motion**: {how it degrades}

## Visual Atmosphere
- **Primary**: {clean / textured / gradient / layered / dark atmospheric}
- **Implementation**: {specific CSS techniques}

## Per-Page Notes
{For each major page, any specific design considerations}

When running standalone (not in the pipeline), the skill guides the frontend build directly — apply the design brief decisions inline as you code rather than writing a separate file.

Composition

saccoai-design-system ───→ saccoai-frontend-design ───→ saccoai-website-rebuild (Phase 2)
saccoai-website-analysis ─┘                          └──→ saccoai-product-builder (Phase 2)

This skill sits between extraction and building. It reads what was extracted and produces creative interpretation that the builders consume. Without it, the builders fall back to _shared/references/build-standards.md defaults — functional but not distinctive.

Standalone Usage

Invoke this skill directly when:

• Building a new frontend from scratch (no extraction phase)
• Redesigning an existing project's visual identity
• Evaluating whether a built site has sufficient design quality
• Creating a design system for a new brand
• The user asks for "better design", "more distinctive", or "less generic"

When used standalone, skip the .saccoai/ output file and apply decisions directly to the code.

Anti-AI-Slop Guardrails

Before finalizing any design brief or build, check against these:

If you catch yourself doing this...	Do this instead
Using Inter or Geist as the only font	Pair with a distinctive display font that creates tension
Purple/blue gradient on white background	Choose a color relationship that reflects the emotional territory
Hero → 3-col features → testimonials → CTA	Design the page structure from the content, not from a template
Uniform border-radius and shadow on all cards	Vary card treatments — some with borders, some with shadow, some flat
Every section has the same padding	Create rhythm with varied spacing
Animations on everything	Pick one or two moments and invest in them
Gray placeholder where a design decision should be	Make the decision. Beige, cream, slate, charcoal, midnight — anything but default gray
Same design you'd give a different client	Start over. Every project is different.