Start

• Every invocation must complete the start questionnaire before Phase 1 begins.
• Do not enter decisions.md, director selection, film selection, architecture, or visual planning until the questionnaire is complete.
• Mirror the user's language in every question and deliverable.
• Keep questions short and ask only one blocking question at a time.
• Run this start questionnaire on every invocation:
  1. Ask how to start:
  • Screenshot: reverse-engineer a visual reference from an image or URL.
  • Step-by-step: let the user choose genre, director, and film.
  • Surprise me: pick a fresh combination that differs from previous work when project history is available.
  2. Ask whether the design should include image placeholders.
  3. Ask for the site's niche and page list before moving into architecture.
• If the environment supports structured questionnaires or forms, use them.
• If the environment does not support structured questionnaires, ask the same items in plain language.
• If the user pre-answers some items in the initial request, confirm or record those answers and only ask for the missing items.
• Phase 1 starts only after all required start-questionnaire items are answered or explicitly 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

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.
• 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/font-moods.md
  • references/data/textures.md
• Read references/anti-garbage.md before finalizing the spec.
• 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.
• 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.

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.

The film is not a spec sheet. The film is research input. The computer-operable workflow starts when those observations are translated into decisions.md, storyboard.md, compiled-spec.md, and implementation.

Problems It Solves

| Problem | What It Looks Like | How This Skill Solves It | |---------|-------------------|--------------------------| | Pacing | Sections are technically valid but feel like a slide deck, not a directed site | Director narrative templates replace the default Hero → Features → Stats → CTA flow | | Space | Components exist but visual weight, distance, hierarchy, and pressure are weak | Forces a Signature Composition per page — no fallback to default grid | | Light | Surface glow only — no real lighting logic, shadow behavior, or material control | Colors sourced from actual film scenes, paired with background-techniques library | | Premium feel | Clean but not expensive, not restrained, not directed enough | Premium Calibration checklist forces explicit "what we will NOT do" decisions | | Uniqueness | After multiple demos, hero posture, section rhythm, and geometry start repeating | Demo Uniqueness Protocol: history audit + Shell-ban list before every new project |

Core Features

| Feature | Description | |---------|-------------| | Reasoning-first | AI must develop an original visual thesis — not select from a preset library | | Director-first | Emotional direction comes from a real film, not generic luxury branding | | Research-first | When web access is available, research the director and film before locking Phase 1 | | Start questionnaire gate | Every invocation must complete the opening questionnaire before Phase 1 begins | | Storyboard-first | Write decisions.md, storyboard.md, compiled-spec.md before any frontend code | | Demo Uniqueness Protocol | Audits prior outputs and enforces a Shell-ban list to prevent repeated shells across projects | | Anti-grid fallback | Grid is allowed as invisible alignment infrastructure — never as the visible default composition | | Sub-agent friendly | Film research, niche research, page scenes, spec slices, and verification can be delegated while one lead agent maintains final coherence |

Workflow

| Phase | Main Work | Output Artifact | |-------|-----------|----------------| | Phase 1 — Decisions | Complete start questionnaire, choose director + film, run uniqueness audit, research if web access available | decisions.md | | Phase 2 — Storyboard | Define site-wide cinematic grammar, write scene thesis per page role, lock signature composition per page | storyboard.md | | Phase 3 — Compiled Spec | Extract camera / interaction / composition / texture / typography per storyboard — shared system last | compiled-spec.md | | Phase 4 — Build & Verify | Implement from spec, add reduced-motion + responsive, validate against anti-garbage rules | HTML / CSS / JS |

Phase 2 internal order (non-negotiable): Site-wide cinematic grammar → per-page scene thesis → per-page signature composition → shared system

Supported Platforms

Claude Code and OpenAI Codex are the two primary platforms. All others are fully supported.

| Tool / Platform | Entry File | Install / Config | |----------------|-----------|-----------------| | Claude Code (primary) | CLAUDE.md | ~/.claude/skills/cinematic-ui | | Codex / ChatGPT (primary) | CODEX.md | $CODEX_HOME/skills/cinematic-ui | | Cursor | .cursor/rules/cinematic-ui.mdc | Already in .cursor/rules/ — works on clone | | Windsurf | .windsurf/rules/cinematic-ui.md | Already in .windsurf/rules/ — works on clone | | GitHub Copilot | .github/copilot-instructions.md | Already in .github/ — works on clone | | Gemini / Antigravity | GEMINI.md | Read at project startup | | Cross-tool shared | AGENTS.md | Universal reference for any agent |

Installation

Claude Code

Windows:

git clone https://github.com/akseolabs-seo/cinematic-ui "$env:USERPROFILE\.claude\skills\cinematic-layout"

macOS / Linux:

git clone https://github.com/akseolabs-seo/cinematic-ui ~/.claude/skills/cinematic-ui

Then invoke with /cinematic-ui inside Claude Code.

Codex / ChatGPT

git clone https://github.com/akseolabs-seo/cinematic-ui $CODEX_HOME/skills/cinematic-ui

Cursor / Windsurf / GitHub Copilot

git clone https://github.com/akseolabs-seo/cinematic-ui

The .cursor/rules/, .windsurf/rules/, and .github/copilot-instructions.md files are already in place. No additional config needed — the rules activate as soon as the repo is present in your project.

Any other tool

Point the tool at this repo or copy the relevant entry file. See the platform table above.

Suggested Prompt Pattern

Use cinematic-layout to build a homepage.
Pick the director and film yourself.
If web access is available, research the director and film first.
Run the Demo Uniqueness Protocol.
Do not reuse shells from previous demos.
Optimize for a great single-page result before building a shared system.

References Library

All reference dat