expressive-style-guide

Quick Reference

Element	Specification
Background Color	`bg-background` (Near-black tone defined in CSS Variable layer)
Foreground Color	`text-foreground` (Highlighted white defined in CSS Variable layer)
Accent Color	`text-primary` / `bg-primary` (Single brand color)
Border Radius	`rounded-lg` (8px) or `rounded-xl` (12px)
Animation Engine	Framer Motion, Spring Physics preferred
Visual Patterns	Spotlight / Parallax / Morph / Ambient Gradient / Mask Reveal / Frosted Overlay / Kinetic Typography (combinable)
Contrast	WCAG AA (≥4.5:1), text on dark backgrounds must meet the standard
Hardcoded Hex	Forbidden — Strictly use semantic Tokens at component layer

Core Mandate

This specification aims to build "Cinematic UI" or "Kinetic Minimalism". The core is to treat the interface as a controlled photographic stage, using light and shadow, materials, and camera logic (camera movement) to elevate digital content to the level of art.

Hard Constraints:

UI Library:
```
shadcn/ui
```
(Only used as underlying structure, must purify visuals by merging styles via
```
cn()
```
, hardcoded style overrides of system Tokens are strictly prohibited).
Styling Engine:
```
Tailwind CSS
```
(Strictly use semantic Token classes, define cinematic colors in CSS Variables layer).
Animation Library:
```
Framer Motion
```
(Core engine. Spring Physics is the preferred driver, supplemented by scroll-driven and parallax animations).

I. Design Philosophy: Cinematic Void

Content as Hero: The interface must absolutely recede. All decorative elements should be stripped away except for the content itself (images, music, artworks).
The Dark Canvas: Background uses a near-black tone defined in CSS Variables (
```
--background
```
), and components use
```
bg-background
```
. Utilize extremely high dynamic range to create dramatic contrast with local lighting.
Camera Work: Animations should not be "jumpy" or "bouncy", but rather "smooth dolly zoom" or "morph".
Tactile Material: Interface objects should have a sense of mass and surface reflection, simulating the texture of physical entities in a darkroom.

II. System Foundations

1. Cinematic Color Tokens

Principle: All colors are defined in the CSS Variables layer, and components strictly use Tailwind semantic classes. Hardcoded Hex values are strictly prohibited in component code.

CSS Variables Definition (Cinematic Tones):

css

:root {
  /* Light Mode is rarely used in cinematic scenarios but must be defined */
  --background: 0 0% 98%;        /* Near-white */
  --foreground: 0 0% 4%;         /* Near-black */
  --card: 0 0% 96%;
  --card-foreground: 0 0% 4%;
  --primary: 220 90% 56%;        /* Brand accent color */
  --primary-foreground: 0 0% 98%;
  --secondary: 0 0% 92%;
  --secondary-foreground: 0 0% 10%;
  --muted: 0 0% 90%;
  --muted-foreground: 0 0% 40%;
  --accent: 0 0% 92%;
  --accent-foreground: 0 0% 10%;
  --border: 0 0% 85%;
  --ring: 220 90% 56%;
}

.dark {
  /* Cinematic core palette - near-black high contrast */
  --background: 0 0% 2%;         /* Near-pure black canvas */
  --foreground: 0 0% 95%;        /* Highlighted white foreground */
  --card: 0 0% 4%;               /* Slightly brightened card */
  --card-foreground: 0 0% 92%;
  --primary: 220 85% 65%;        /* Accent color after spectral shift */
  --primary-foreground: 0 0% 2%;
  --secondary: 0 0% 8%;
  --secondary-foreground: 0 0% 88%;
  --muted: 0 0% 12%;
  --muted-foreground: 0 0% 55%;
  --accent: 0 0% 10%;
  --accent-foreground: 0 0% 90%;
  --border: 0 0% 14%;            /* Extremely subtle border */
  --ring: 220 85% 65%;
}

Component Layer Usage Example:

tsx

// ✅ Correct — Use semantic tokens
<div className="bg-background text-foreground">
<div className="bg-card border-border">
<span className="text-muted-foreground">

// ❌ Forbidden — Hardcoded Hex
<div className="bg-[#030303] text-[#ffffff]">
<div style={{ background: '#000000' }}>

2. Cinematic Lighting

Light and shadow effects are expressed through tokenized

border

and

opacity

, hardcoded RGBA is forbidden.

Reflective Sheen: Subtle reflection on card top uses tokenized border:
- Primary Sheen:
```
border-t border-foreground/20
```
  (Highlighted top edge)
- Ambient Border:
```
border border-border
```
  (Overall subtle border)
Ambient Glow: Use background blur halo only in extremely restrained scenarios, with opacity controlled at 5-8%:
- ```
bg-primary/5
```
  or
```
bg-primary/8
```
  as ambient background for content
Blur Layers: Popups use
```
backdrop-blur-xl
```
with semantic background color:
- ```
bg-background/80 backdrop-blur-xl
```

3. Kinetic Physics

Spring Physics (Interaction-driven)

Camera Movement (Dolly/Morph): For layout switching, pursue stability and coherence.
ts
```
const dolly = { type: "spring", stiffness: 280, damping: 28, mass: 1 };
```
Tactile Precision: For micro-interactions (clicks, hovers), fast and without oscillation.
ts
```
const tactile = { type: "spring", stiffness: 380, damping: 30, mass: 0.8 };
```

Reveal: For new element entry, use smooth Expo easing.

const reveal = { duration: 1, ease: [0.16, 1, 0.3, 1] };

Scroll-Driven Animations

Parallax Scrolling: Achieve differential movement between foreground/background via

useScroll

useTransform

const { scrollYProgress } = useScroll({ target: ref });
const y = useTransform(scrollYProgress, [0, 1], ["0%", "-20%"]);

Mask Reveal: Drive

clipPath

opacity

reveal via

scrollYProgress

const opacity = useTransform(scrollYProgress, [0.2, 0.6], [0, 1]);
const clipPath = useTransform(scrollYProgress, [0, 1],
  ["inset(100% 0 0 0)", "inset(0% 0 0 0)"]
);

Stagger Orchestration

List/grid child elements use

staggerChildren

for cascading entry:

const container = { animate: { transition: { staggerChildren: 0.08 } } };
const item = {
  initial: { opacity: 0, y: 24 },
  animate: { opacity: 1, y: 0, transition: reveal }
};

4. Display Typography

Display Heading: Headings should have dramatic contrast.
- Scale:
```
text-5xl
```
  to
```
text-9xl
```
  .
- Tracking:
```
tracking-tighter
```
  (-0.05em+).
- Color:
```
text-foreground
```
  (Hardcoded white is strictly prohibited).
Mono Secondary: All auxiliary information (year, metadata) must use Mono fonts to enhance industrial precision.
- Font:
```
JetBrains Mono
```
  or
```
Geist Mono
```
  .
- Color:
```
text-muted-foreground
```
  .
Body Text: Line height
```
leading-relaxed
```
(1.625) to ensure readability on dark backgrounds.

III. Visual Mode Palette

The following modes can be used independently or combined and layered. Choose the best combination based on content type. Avoid overusing all modes in a single project — select 2-3 to establish a unified visual language.

1. Spotlight

Mouse-tracking local lighting that makes content emerge from darkness.

Track mouse coordinates via

useMotionTemplate

useMotionValue

to generate

radial-gradient

Aperture radius 240-320px, only the illuminated area displays borders and fine textures.
Suitable for: Card grids, art galleries, feature showcases.

2. Parallax Depth

Differential movement between foreground/background layers creates spatial depth.

Background layer follows scroll at 0.3-0.5x speed, foreground at 1.0x speed.
Map
```
translateY
```
via
```
useScroll
```
+
```
useTransform
```
.
Can be combined with
```
scale
```
transform to simulate "dolly in".
Suitable for: Landing Page Hero, long-scroll narratives, product showcases.

3. Morph Transition

Morph interpolation between elements establishes spatial continuity.

Mandatory use of Framer Motion's
```
layoutId
```
to achieve seamless cross-view deformation.
Cover images perform continuous interpolation of size/position/border-radius between thumbnail → detail page.
Combine with
```
AnimatePresence
```
to ensure complete exit animations.
Suitable for: Detail expansion, navigation switching, state transitions.

4. Ambient Gradient

Low-saturation dynamic gradient background creates immersive atmosphere.

Use

bg-gradient-to-*

with tokenized colors:

from-background via-muted/10 to-background

Can slowly cycle gradient angle or position via
```
animate
```
(duration: 8-15s).
Saturation is strictly controlled at 5-15%, high-saturation gradients are forbidden.
Suitable for: Music player backgrounds, brand page atmosphere, loading states.

5. Mask Reveal

Scroll-driven content reveal creates dramatic unveiling effects.

Achieve geometric shape reveal via
```
clipPath
```
animation.
Supports multiple reveal forms: vertical wipe, central circle expansion, diagonal cut-in.
Combine with
```
opacity
```
transition to prevent hard-edge flicker.
Suitable for: Section entry, image showcases, timeline nodes.

6. Frosted Overlay

Frosted glass panel + depth-of-field blur establishes hierarchy and focus.

Panel uses

bg-background/60 backdrop-blur-xl border border-border

Background layer simultaneously applies
```
scale(1.02)
```
+
```
blur(4px)
```
to simulate depth of field.
Overlay entry uses
```
dolly
```
spring parameters, exit uses
```
reveal
```
parameters.
Suitable for: Modal/Dialog, sidebar, detail pop-up panels.

7. Kinetic Typography

Dramatic orchestration of text entry makes typography itself a visual focus.

Headings enter character-by-character or word-by-word, cascaded via
```
staggerChildren: 0.03-0.06
```
.
Each character independently applies
```
opacity
```
+
```
y
```
+
```
filter: blur()
```
transitions.
Large headings can be combined with a slight scale transform from 1.1 → 1.0.
Suitable for: Hero headings, brand declarations, section titles.

IV. Implementation Specs

Cinematic Overrides for shadcn/ui

All modifications merge styles via

cn()

, use semantic tokens, and hardcoded color values are forbidden.

Button

tsx

// Primary — High-contrast action button
<Button className={cn(
  "bg-primary text-primary-foreground",
  "rounded-lg tracking-wide font-medium",
  "transition-none" // Handled by Framer Motion
)}>
  <motion.span whileTap={{ scale: 0.97 }} transition={tactile}>
    Action
  </motion.span>
</Button>

// Ghost — Cinematic ghost button
<Button variant="ghost" className={cn(
  "text-muted-foreground hover:text-foreground",
  "hover:bg-accent/50"
)}>
  Secondary
</Button>

Card (Cinematic Card)

tsx

<motion.div className={cn(
  "bg-card border border-border rounded-xl overflow-hidden",
  "border-t-foreground/15" // Top reflective sheen
)}>
  {/* Cover image defaults to reduced brightness, restores on interaction */}
  <motion.img
    className="w-full object-cover brightness-[0.6]"
    whileHover={{ brightness: 1 }}
  />
  <div className="p-6">
    <h3 className="text-foreground text-lg font-semibold tracking-tight">
      {title}
    </h3>
    <p className="text-muted-foreground text-sm font-mono mt-1">
      {metadata}
    </p>
  </div>
</motion.div>

Dialog (Cinematic Popup)

tsx

<Dialog>
  <DialogOverlay className={cn(
    "bg-background/80 backdrop-blur-xl"
  )} />
  <DialogContent className={cn(
    "bg-card border border-border rounded-xl",
    "shadow-none"
  )}>
    {/* Content uses AnimatePresence for entry orchestration */}
    <AnimatePresence mode="wait">
      <motion.div
        initial={{ opacity: 0, y: 16 }}
        animate={{ opacity: 1, y: 0 }}
        exit={{ opacity: 0, y: -8 }}
        transition={dolly}
      >
        {children}
      </motion.div>
    </AnimatePresence>
  </DialogContent>
</Dialog>

Navigation (Cinematic Navigation)

tsx

<nav className={cn(
  "fixed top-0 w-full z-50",
  "bg-background/60 backdrop-blur-lg border-b border-border"
)}>
  <div className="flex items-center justify-between px-8 h-16">
    <span className="text-foreground font-semibold tracking-tight">
      {brand}
    </span>
    <div className="flex gap-6 text-muted-foreground">
      {links.map(link => (
        <motion.a
          key={link.href}
          className="hover:text-foreground transition-colors"
          whileHover={{ y: -1 }}
          transition={tactile}
        >
          {link.label}
        </motion.a>
      ))}
    </div>
  </div>
</nav>

Asymmetric Bento Grid

The grid breaks equal-width monotony to create visual rhythm:

Hero Item:
```
col-span-2 row-span-2
```
— Main visual focus.
Vertical/Square: Staggered arrangement to create visual rhythm.
Gap:
```
gap-4
```
or
```
gap-6
```
, use tokenized spacing.
Mobile: Halve the spacing (
```
gap-2
```
), but maintain sufficient padding (
```
p-4
```
).

tsx

<div className="grid grid-cols-2 md:grid-cols-4 gap-4 md:gap-6">
  <div className="col-span-2 row-span-2">{/* Hero Card */}</div>
  <div className="col-span-1">{/* Vertical Card */}</div>
  <div className="col-span-1">{/* Square Card */}</div>
</div>

Shared Element Transition

Mandatory use of Framer Motion's
```
layoutId
```
.
Cover images must perform seamless interpolation transitions between forms, and instant flicker or hard cuts between pages are strictly prohibited.
Combine with
```
AnimatePresence
```
to manage component lifecycle.

tsx

<motion.div layoutId={`card-${id}`} transition={dolly}>
  <motion.img layoutId={`image-${id}`} src={cover} />
</motion.div>

V. The Cinematic Audit

Token Compliance

Token Check — Are there hardcoded Hex values (e.g.,
```
#030303
```
,
```
#ffffff
```
) in component code? Do all colors use semantic classes like
```
bg-background
```
/
```
text-foreground
```
/
```
border-border
```
?
CSS Variable Check — Are cinematic tones correctly defined in
```
:root
```
/
```
.dark
```
CSS Variables?

Visual & Material

Lighting Logic — Are light and shadow effects used appropriately? Is omnidirectional uniform lighting avoided?
Material Check — Do all containers have top reflection (
```
border-t-foreground/15
```
)? Do borders use
```
border-border
```
?
Imagery Authenticity — Are cover images high-quality photography or 3D renders? Are there cheap vector or gradient placeholders?

Animation Quality

Physics Check — Do interaction animations use Spring Physics? Are there linear or ease-in-out animations? Is damping sufficient to ensure stability?
Continuity Check — Are
```
layoutId
```
applied to image transitions? Does detail page entry use
```
AnimatePresence
```
?
Scroll Motion Check — Are scroll-driven animations (parallax/mask reveal) used appropriately? Are there unnecessary JS scroll listeners?

Pattern Diversity

Variety Check — Does the project over-rely on a single visual pattern (e.g., only using spotlight)? Are 2-3 complementary patterns selected based on content type?
Composition Check — When multiple patterns are layered, is visual restraint maintained? Are there performance issues or aesthetic fatigue caused by over-stacking?

Accessibility

Contrast Safety — Does all text on dark backgrounds (especially
```
text-muted-foreground
```
) meet a contrast ratio of ≥ 4.5:1?
Motion Safety — Is
```
prefers-reduced-motion
```
respected? Are parallax and complex entry animations disabled when enabled?

Reference Resources

Example Project: The
```
example/
```
directory contains a complete demo app called Aero Music, showcasing the full implementation of Bento layout, spotlight mask, and camera movement.

Composition Notes

This section is for the
design-director
skill to use in multi-style fusion scenarios. Define which attributes in this style guide are hard constraints (cannot be overridden even in mixed modes) and which are soft constraints (can be adjusted by the Director based on project needs).

Hard Constraints — Non-overridable

ID	Attribute	Specification Value	Reason
E.H1	Animation Engine	Framer Motion, Spring Physics preferred	Core driver of cinematic texture. Replacing with CSS transitions will lose all visual characteristics
E.H2	Dark Canvas	Dark background as default canvas (within Expressive areas)	Light and shadow drama relies on dark base. Light backgrounds cannot implement core visual patterns like spotlight and ambient gradient
E.H3	Tokenization	Hardcoded Hex forbidden, semantic tokens used at component layer	Infrastructure for cross-style fusion, shared by all styles
E.H4	Content as Hero	Decorative elements must recede behind content (images, music, works)	Core philosophy of this style — interface recedes, content takes center stage
E.H5	Contrast	WCAG AA (≥4.5:1)	Mandatory accessibility requirement, especially for light text on dark backgrounds

Soft Constraints — Overridable by Director

ID	Attribute	Default Value	Director Adjustable Range	Trigger Condition
E.S1	Border Radius	`rounded-lg` (8px) / `rounded-xl` (12px)	Can be reduced to `rounded-md` (6px)	When Minimal is the main project style and Expressive is only used for auxiliary areas
E.S2	Animation Duration Upper Limit	0.3–1.5s (complete cinematic camera movement)	Upper limit can be reduced to 0.8s	When the overall project rhythm is fast, or Minimal/Swiss is the main style
E.S3	Color Space	HSL	Can be converted to oklch	Recommended to unify with oklch in mixed projects — better perceptual uniformity, more natural gradient seams
E.S4	Dark Background Lightness	`hsl(0 0% 2%)` / `oklch(0.08 0 0)` near pure black	Can be brightened to `oklch(0.145 0 0)` ≈ #1A1A1A	When needing to unify dark mode baseline with Minimal/Swiss areas
E.S5	Asymmetric Bento Grid	Free asymmetric layout	Can be aligned to 8pt baseline grid (column width and spacing are multiples of 8px)	When Swiss is one of the project styles and global grid alignment is required
E.S6	Stagger Interval	0.08s	Can be shortened to 0.04–0.06s	When the overall project rhythm is fast
E.S7	Parallax Scroll Intensity	0.3–0.5x speed difference	Can be reduced to 0.1–0.2x speed difference	When Minimal is the main style and a more restrained scrolling experience is needed