cinematic-ui

name

cinematic-ui

description

Design and build websites with film-inspired visual systems, director-driven art direction, storyboard-first layout planning, and cinematic motion. Use when the user asks for a cinematic site, movie-style landing page, director-inspired UI, film-noir, sci-fi, romance, thriller, action, animation, or a movie-like website aesthetic, including requests phrased in Chinese. Do not use for generic web design unless the user explicitly wants a film or director reference.

Cinematic Layout

Primary Platforms

This skill is built and maintained for Claude Code and OpenAI Codex as the two primary runtimes.

Claude Code

• Invoke with /cinematic-ui.
• Project memory and Claude-specific notes live in CLAUDE.md.
• Install path (Windows): C:\Users\<your-user>\.claude\skills\cinematic-layout
• Install path (macOS / Linux): ~/.claude/skills/cinematic-ui

OpenAI Codex / ChatGPT

• Codex-specific context lives in CODEX.md.
• Install path: $CODEX_HOME/skills/cinematic-ui

Additional compatibility files:

• GEMINI.md — Gemini / Antigravity-style workflows
• AGENTS.md — shared cross-tool reference
• .github/copilot-instructions.md — GitHub Copilot
• .cursor/rules/cinematic-ui.mdc — Cursor (auto-loaded on clone)
• .windsurf/rules/cinematic-ui.md — Windsurf (auto-loaded on clone)

---

Design the site like a film production, not like a generic landing page. Treat this as a research-and-translation skill plus a design-library skill. Its job is to study film references, extract usable cinematic signals, then turn those signals into page narrative, section structure, motion direction, and implementable web specs. The core mechanism is fixed: use a director and a specific film to determine the site's emotional language, then translate that language into web structure and implementation. Do not replace this with generic premium-brand logic. Do not confuse the film with the workflow artifact. The film is research input and emotional source material. The computer-operable workflow begins only when those observations are translated into decisions.md, storyboard.md, compiled-spec.md, and implementation.

Start

• Every invocation must complete the start questionnaire before Phase 1 begins, but treat it as a fast-path, not a stall. Present the whole short questionnaire at once with defaults already filled, so the user can confirm in one reply instead of composing answers from scratch.
• Do not enter decisions.md, director selection, film selection, architecture, or visual planning until the questionnaire is resolved (answered or defaulted).
• Mirror the user's language in every question and deliverable.
• Run this start questionnaire on every invocation:
  1. Ask how to start. Surprise me is the default — lead with it and pre-select it:
  • Surprise me (default): take full creative direction. Autonomously pick a fresh genre + director + film combination that differs from any previous work when project history is available, then proceed.
  • Step-by-step: let the user choose genre, director, and film.
  • Screenshot: reverse-engineer a visual reference from an image or URL.
  2. Ask whether the design should include image placeholders (default: yes).
  3. Ask for the site's niche and page list (default: infer both from the user's request, then state the inference for confirmation).
• If the environment supports structured questionnaires or forms, use them and pre-select the defaults above.
• If the environment does not support structured questionnaires, ask the same items in plain language with the defaults shown inline.
• Operate autonomously when input is thin: if the user gives a go-ahead, declines to choose, or leaves items blank, do not block. Proceed with Surprise me plus justified assumptions for the remaining items, state those assumptions in decisions.md, and keep building. Ask a clarifying question only when a missing answer would genuinely change the design — never just to appear careful.
• If the user pre-answers some items in the initial request, confirm or record those answers and only ask for the missing items.
• Read references/autonomous-direction.md to run this autonomous, decide-don't-ask posture across all four phases.
• Phase 1 starts only after all required start-questionnaire items are answered, defaulted, or inferred from the user's request.

Demo Uniqueness Protocol

Use this whenever the same user has already used this skill to create one or more other sites, demos, or homepage concepts.

• Treat prior outputs for the same user as design-history context, not as reusable shells.
• Before Phase 1 is complete, inspect the immediately previous outputs when available and record a uniqueness audit in decisions.md.
• Write a Previous-work audit that names the recurring traits most likely to repeat. Examples:
  • left-copy right-object hero
  • top nav plus stacked framed panels
  • repeated rounded premium cards
  • pill metadata row
  • dark luxury palette with thin borders
• Write a Shell-ban list for the new project. These are layout traits that are explicitly forbidden because they would make the new work too similar to prior work.
• Write a Primary composition family for the new project before any page design begins. Examples:
  • full-bleed stage
  • corridor
  • vertical tower
  • archive wall
  • panoramic slab
  • cutaway monolith
• The new project must choose a different primary composition family from the user's most recent comparable output unless the user explicitly asks for an intentional sequel.
• If the user asks for multiple different sites over time, prioritize uniqueness across site shell, hero posture, section rhythm, navigation posture, density pattern, and dominant geometry, not just color or typography.
• A new demo fails if its wireframe would still look like a previous demo after removing color, type styling, and decorative effects.
• If project history is unavailable, state that and still write a Shell-ban list against the most common fallback templates you might otherwise drift toward.

Operating Model

Use four strict phases. Do not skip forward. Keep each phase's output in its own markdown file inside the working project.

1. Phase 1: decisions
2. Phase 2: storyboard
3. Phase 3: compiled spec
4. Phase 4: build and verify

Inside Phases 2 and 3, follow this order without skipping:

1. Define the site-wide cinematic grammar.
2. Write one independent scene thesis for each major page role.
3. Lock one irreplaceable signature composition per page.
4. Derive the shared system only after the page compositions are already clear.

Read references/output-templates.md before creating those files.

Delegation Model

• If the environment supports sub-agents or parallel workers, use them by default after the director and film are locked.
• Keep one lead agent responsible for the site-wide cinematic grammar and final coherence.
• Delegate bounded sidecar tasks such as:
  • film or niche reference research
  • page-role scene exploration for distinct pages
  • compiled-spec drafting for disjoint page roles
  • implementation or verification on separate files
• Do not let multiple agents independently redefine the director, film, or site-wide visual thesis.
• Merge delegated work back into one directed system. The result must still feel like one film, not a committee.
• Do not skip delegation unless the task is too small to benefit from it or the environment does not support sub-agents.

Progressive Loading

Keep SKILL.md lean. Load only the references needed for the current phase.

Always read first

• references/library-index.md
• references/premium-calibration.md
• references/autonomous-direction.md

Phase 1: Decisions

• Read references/data/directors-200.md only.
• If sub-agents are available, delegate film research, niche research, or reference breakdown as separate bounded tasks after the user direction is clear.
• If the user has prior sites or demos in the workspace, review them just enough to identify what must not repeat.
• If the user starts from a screenshot or live site, inspect that reference first and infer a likely genre, director, and film. Ask for confirmation before committing.
• When web access is available, research the chosen director and film before finalizing the phase. This is required, not optional.
• Use external sources to gather richer creative input such as:
  • film palette and lighting behavior
  • cinematography patterns, framing logic, and scene rhythm
  • production design or material cues
  • director signature techniques
  • 2-3 premium sites in the same niche
• Prefer primary or authoritative sources when available, then add secondary analysis only to deepen interpretation.
• Record the research sources and a short interpretation note. Do not dump plot summaries or generic trivia.
• If web access is unavailable, say so explicitly and continue with best-effort inference from local libraries. Mark the result as a weaker research pass.
• If the user provides references, do not copy them whole. Read references/reference-protocol.md and decompose each reference into traits such as rhythm, materiality, typography, framing, or image treatment.
• Record the uniqueness audit, shell-ban list, and primary composition family in decisions.md.
• Generate creative directions before committing. Per references/autonomous-direction.md, draft 3 candidate director+film directions (at least 2 genuinely unconventional), then autonomously select the one with the strongest identity-to-usability ratio unless the user asked to choose. Record the chosen direction and a one-line rationale.
• Write decisions.md.

Phase 2: Storyboard

• Read these files one at a time, not all at once:
  • references/anti-convergence.md
  • references/data/hero-archetypes.md
  • references/data/narrative-beats.md
  • references/data/section-functions.md
  • references/data/section-archetypes.md
• Use references/data/dna-index.tsv to cast 2-3 compatible design DNA sources by mood, font direction, shape language, motion, restraint, density, and material richness.
• Read references/data/design-dna-db.txt only when the index points to a promising source and deeper site-level DNA details are needed.
• Define the site-wide cinematic grammar before designing any individual page. Capture:
  • page-shell logic
  • navigation posture
  • framing rules
  • density cadence
  • recurring material or atmospheric layers
  • composition families that fit the chosen film
• Make sure the selected page-shell logic and composition family do not violate the shell-ban list from Phase 1.
• Build a director brief with:
  • one-sentence visual thesis
  • 3 signature techniques and their web translation
  • exact color tokens
  • typography direction
  • motion rules
• Run the prestige calibration from references/premium-calibration.md.
• For every major page role, write an independent scene thesis before defining shared components. Treat each page as a standalone scene or poster first, then connect the pages into one site.
• If sub-agents are available, assign distinct page roles to different agents only after the site-wide cinematic grammar is approved.
• Define one page-level visual thesis per page. This is the single dominant idea that makes the page memorable. Examples: monumental type, sculptural light, editorial framing, void plus glow, object-as-stage. Everything else must support this idea rather than compete with it.
• Write a hero dominance statement explaining exactly why the hero feels expensive or cinematic without relying on generic gradients or generic app UI.
• Define one irreplaceable signature composition per page before introducing reusable layout primitives.
• Map each page to a narrative arc instead of defaulting to Hero -> Features -> Stats -> CTA.
• Apply the anti-convergence system from references/anti-convergence.md when choosing hero archetypes, narrative arcs, and section archetypes.
• Write storyboard.md.
• Get user approval before moving to Phase 3 when the task is collaborative or exploratory.

Phase 3: Compiled Spec

• Read references/implementation-guardrails.md before extracting final CSS and JS.
• Read only the specific entries needed for the approved storyboard:
  • references/data/camera-shots-50.md
  • references/data/interaction-effects-50.md
  • references/data/compositions.md
  • references/data/visual-elements.md
  • references/data/background-techniques.md
  • references/data/typography-cinema.md
  • references/data/color-grades.md
  • references/data/brand-palettes.md (only when the user brings their own brand tokens to honor; one worked example included — pick one source of truth, never mix with color-grades.md)
  • references/data/font-moods.md
  • references/data/textures.md
• Read references/anti-garbage.md before finalizing the spec.
• Run the palette exploration from references/autonomous-direction.md before locking color tokens: generate 3 palette candidates (restrained, unusual, tension-based) for the chosen direction, then select one. Follow the Color Direction rule below — anchor on saturated primaries and vary the palette family across demos; do not default to warm/sepia/amber unless the chosen film genuinely calls for it.
• Lock each page's signature composition before deriving shared layout primitives.
• Shared systems come last. Extract navigation, footer, spacing rhythm, typography, tokens, and utilities only after the page-specific compositions are already clear.
• If sub-agents are available, delegate disjoint page-spec extraction or implementation tasks, then merge them back under one lead agent review.
• Respect a strict interaction budget:
  • maximum 1 heavy interaction per page
  • maximum 2 attention-seeking reveal patterns per page
  • the remaining motion must stay subordinate to the page's visual thesis
• Prefer fewer but stronger gestures over many clever effects.
• Translate premium cues into surfaces, spacing, type hierarchy, edge treatment, and atmospheric layers, not just animation.
• Grid and flex may be used as invisible alignment infrastructure, but the visible composition must not collapse into a default card matrix unless the chosen film explicitly supports that logic.
• Create an entrance map per page before writing section specs.
• fadeUp / opacity + translateY may appear at most 2 times per page.
• Use at least 4 distinct entrance types per page when the page has enough sections to support that range.
• If a selected interaction-effect id is JS-required under references/implementation-guardrails.md, the full JS is mandatory in compiled-spec.md.
• Include the External Library Decision block from references/implementation-guardrails.md in compiled-spec.md.
• Run the Phase 3 quality checklist from references/implementation-guardrails.md before treating the spec as complete.
• Do not invent core interactions or atmospheric devices from memory when an appropriate library entry already exists.
• For each page, record the selected library source ids for:
  • camera / reveal behavior
  • interaction behavior
  • composition
  • typography treatment
  • atmospheric/background technique when used
• Every heavy interaction, standout reveal, hero atmosphere layer, and signature composition must cite its library entry id in compiled-spec.md.
• If a custom effect is still necessary, mark it explicitly as Custom, explain why the library was insufficient, and keep it subordinate to the chosen film language.
• Extract complete CSS for layout, entrances, and interactions.
• Include complete JS whenever the selected interaction requires it.
• Write compiled-spec.md as the only source of truth for implementation.

Phase 4: Build And Verify

• Read only:
  • compiled-spec.md
  • references/anti-garbage.md
  • references/implementation-guardrails.md
• Build from the spec without improvising new layout logic.
• Add reduced-motion handling and responsive behavior without breaking the chosen film language.
• Verify the output against the storyboard and compiled spec.
• Run the self-critique and batch refinement loop from references/autonomous-direction.md: score the build harshly (strong / mixed / weak), name the highest-impact upgrades, then apply them in grouped passes (art direction, layout, typography, color, motion, mobile, polish). Do not stop at cosmetic cleanup; refine until the site feels authored. If it still looks AI-generated, say so and fix it.
• Use the Screening Room and Post-Screening Adjustments rules from references/implementation-guardrails.md when refining the result after the first build.

Hard Rules

• Preserve the chosen director and film language through color, type, spacing, composition, and motion.
• Keep the director and film as the primary source of feeling. Use premium calibration to sharpen the result, not to overwrite the chosen cinematic DNA.
• Keep director names, film titles, chapter markers, calibration jargon, and workflow metadata inside the working files by default, not in the user-facing UI.
• Do not expose labels such as chapter, director, film, calibrated, report build, treatment, or similar process language in the final interface unless the user explicitly asks for a meta/editorial treatment.
• Vary section rhythm. Include a mix of spectacle, dense information, and breathing room.
• Use at least 4 distinct entrance patterns per page when the page has enough sections.
• Do not let adjacent sections reveal the same way.
• Include visual structure beyond plain text blocks. Hero sections need at least 3 visual elements. Most other sections need at least 1-2.
• Make each page legible around one big visual idea. Do not let every section introduce a new concept.
• Define the site-wide cinematic grammar first, then page scenes, then irreplaceable page compositions, and only then the shared system.
• When the same user has prior outputs, force uniqueness at the wireframe level. Do not let a new site reuse the previous site's shell with only different colors, copy, or surface styling.
• Interior pages must feel like new scenes in the same film, not simplified versions of the homepage.
• Every major page role needs one signature composition that cannot be replaced by a generic product-marketing grid or default template layout.
• A site style is not valid until the homepage and all major page roles express the chosen director through layout, pacing, hierarchy, and composition, not only through color, typography, or surface styling.
• Treat grid as infrastructure, not composition. If a section still works unchanged as a generic two-by-two or three-column product grid, the composition is too weak.
• Design interior pages as standalone scenes first. Shared patterns must support those scenes, not flatten them.
• Treat restraint as a design tool. High-end work often removes 20 percent of the obvious moves rather than adding 20 percent more detail.
• Prefer exact tokens and implementation notes over vague adjectives.
• If web research or a referenced site is unavailable, state that constraint and continue with best-effort inference instead of stalling.
• Never treat the film itself as a spec sheet, component inventory, or computer workflow. Research the film as cinema, then formalize only the web translation.

Color Direction

This is a bias on defaults and selection, not an override of the film. A deliberately chosen warm film (for example In the Mood for Love, Dune, The Godfather) keeps its true palette — preserving the chosen film language always wins.

• Work in the saturated, primary-leaning color space — blue, red, green and their confident relatives (cobalt, electric blue, scarlet, oxblood, emerald, viridian, chartreuse) — instead of warm earth tones. This is a space to rotate through, not a fixed trio. Each project leads with one direction (red-led, green-led, cobalt-led, or a deliberate tension pair) and that lead rotates from project to project. Do not paint blue+red+green together every time — that is just a new way to converge. These are anchors, not floods: most of the interface still rides on neutrals and surfaces, with color concentrated on actions, emphasis, and rare cinematic moments.
• Do not default to brown, sepia, amber, tan, or parchment warmth. The color-grade library leans warm (most presets carry a sepia() wash) and the legacy token default was a tan gold — reach past that bias first. Pick a warm/earthy grade only when the chosen film genuinely demands it, and say why.
• "Random" means vary the palette family aggressively across projects so the work never converges on one look — warm or primary. Derive the palette lead from the project seed (see Cross-Invocation Variation in references/anti-convergence.md), not from agent habit. Never literal randomness, never neon chaos. Every palette must hold readable contrast (target WCAG AA for text and UI) and feel intentional.
• When project history exists, the new palette family must differ from the user's most recent comparable output, the same way composition must (see Demo Uniqueness Protocol).
• Detailed selection logic, palette exploration, and the surprise rule live in references/autonomous-direction.md.

Autonomous Operating Mode

• Behave like a senior creative director who also ships code: infer, propose, choose, and justify rather than waiting for the user to specify every detail. Decide what you can; ask only when a missing answer would genuinely change the design (cap at the most important blocking questions).
• Introduce at least one controlled, tasteful surprise per project — a single art-direction move the user likely would not have requested but will appreciate — while keeping it usable, accessible, and coherent with the chosen film. Full rules in references/autonomous-direction.md.

Universal, Brand-Agnostic

• This is a universal cinematic generator, not the house style of any one brand. Never assume, default to, or steer toward a specific company's palette, logo, or identity.
• If the user supplies their own brand (tokens, logo, existing site), translate their identity through the chosen film. If they do not, generate a fresh identity per the Color Direction and variation rules — do not reach for a built-in brand palette.
• references/data/brand-palettes.md is an optional bring-your-own-brand integration guide with one worked example; treat it as a pattern for plugging in any brand, never as the default look.

Cross-Invocation Variation

• Every invocation should produce a visibly different style, even with no shared project history. Style is derived from the director + film, so wide, non-repeating director+film selection is the main lever — it propagates to palette, type, composition, and motion downstream.
• Drive selection from the project seed and span the full library; do not keep landing on the same famous directors or the same palette lead. Follow the Cross-Invocation Variation rules in references/anti-convergence.md.

Anti-Patterns

• Do not output a generic gradient hero with centered copy unless the source film genuinely supports it.
• Do not watermark the hero or navigation with director names, film titles, chapter labels, or workflow tags masquerading as premium microcopy.
• Do not reuse the same hover, reveal, or card pattern in every section.
• Do not let the page become a motion demo or effect sampler.
• Do not use references as a layout template. Borrow dimensions of quality, not full compositions.
• Do not let shared containers or reusable cards erase page-specific scene identity.
• Do not decide the shared component system before page-level compositions are locked.
• Do not reuse the previous demo's hero posture, navigation posture, section rhythm, or dominant geometry unless the user explicitly requests continuity.
• Do not read the entire library at once.
• Do not jump from user request directly to HTML without writing decisions.md, storyboard.md, and compiled-spec.md.

File Guide

• Use references/library-index.md to decide which library to load.
• Use references/output-templates.md to structure deliverables.
• Use references/premium-calibration.md to decide what makes the page feel expensive without breaking the cinematic concept.
• Use references/reference-protocol.md when the user provides visual references but wants to avoid template copying.
• Use references/anti-garbage.md as the final filter before coding.