sigil-scene

Skill — sigil-scene

One scene per file. The page composes scenes. Animation lives next to its rendering. Tokens drive timing.

What is a "scene"?

A scene is a self-contained named visual or animated block that the page composes — for example HeroDiagram, PresetMorphScene, CliVoronoi, LayerStackDemo. Scenes are NOT generic components: they're page-specific, they may own state and keyframes, and they exist primarily to extract long inline JSX out of app/page.tsx-style files.

The convention solves the "1,300-line page.tsx" problem: each named visual becomes its own file, the page becomes a thin composition file, and an agent asked to "tweak the hero diagram animation" can grep HeroDiagram.scene.tsx or HeroDiagram.tsx and find everything in one place.

Where scenes live

apps/web/components/landing/scenes/
  PresetMorphScene.tsx      ← extracted from app/page.tsx
  CliDiagram.tsx            ← skeleton diagrams + voronoi math
  HeroDiagram.tsx           ← (when extracted)
  ...

The naming convention is PascalCase + descriptive (PresetMorphScene, not MorphScene). The Scene suffix is optional for unambiguous names like CliDiagram or HeroLogoField.

When to extract a scene

Extract into a scene file when ANY of the following are true:

• Inline JSX block exceeds ~80 lines
• The block owns its own useState/useEffect
• The block injects its own <style> or @keyframes block
• The block defines its own data const (e.g. MINI_PRESETS, CLI_VORONOI_TILES)
• The block needs to be reused on more than one page

Do NOT extract when:

• The block is < 30 lines and has no state
• The block is tightly coupled to the page's LandingSection / shared helpers
• Extraction would require re-importing the same useOptional* hooks

Scene file structure

// apps/web/components/landing/scenes/HeroDiagram.tsx
"use client";

import { useState } from "react";
import { /* @sigil-ui/components imports */ } from "@sigil-ui/components";

/* Scene-local data constants live at the top of the file. Export them
   if the page composes the scene across multiple instances, otherwise
   keep them private. */
export const HERO_PRESETS = [/* ... */];

/* Local types for the scene's public shape. */
export type HeroDiagramProps = {
  index: number;
  setIndex: (i: number) => void;
};

/* The scene itself. Owns its render, state where applicable,
   keyframes (inline `<style>` block at the bottom), and any
   pure helpers that aren't worth a separate file. */
export function HeroDiagram({ index, setIndex }: HeroDiagramProps) {
  return (
    <div /* ... */>
      {/* render */}
    </div>
  );
}