expressive-style-guide

• 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).

1. Content as Hero: The interface must absolutely recede. All decorative elements should be stripped away except for the content itself (images, music, artworks).
2. 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.
3. Camera Work: Animations should not be "jumpy" or "bouncy", but rather "smooth dolly zoom" or "morph".
4. Tactile Material: Interface objects should have a sense of mass and surface reflection, simulating the texture of physical entities in a darkroom.

border

opacity

• 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

• 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.
  ts

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

• Parallax Scrolling: Achieve differential movement between foreground/background via

  useScroll

  +

  useTransform

  .
  ts

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

• Mask Reveal: Drive

  clipPath

  or

  opacity

  reveal via

  scrollYProgress

  .
  ts

  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)"]
  );

• List/grid child elements use

  staggerChildren

  for cascading entry:
  ts

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

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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.

• 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

  ).

<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>

• 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.

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

• 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?

• 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?

• 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?

• 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?

• 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?

• 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.

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).