StarVision Theme Extraction

StarVision Extraction Loop

This loop is triggered when a user wants to create a new StarSpec wireframe theme from screenshots, PDFs, or textual guidelines.

1. Metadata Ingestion

The extraction process starts by gathering all available information. The theme.toml manifest is the Hard Constraint.

• Screenshots: Analyze .png or .jpg files for visual patterns.
• Theme Manifest: Read theme.toml (if present).
• Style Guides: Read any provided .pdf or textual descriptions.

Theme Manifest Priority

Values in theme.toml MUST be respected over visual analysis.

• If theme.toml defines brand.primary = "#FF0000", use that even if the screenshot looks blue.
• Partial manifests are common; only the defined fields are mandatory.

2. Visual Analysis Pillar

Perform the three-pillar analysis defined in the StarVision Spec:

1. Chromatic: Extract primary, background, and semantic HEX codes.
2. Geometry: Identify border radii, stroke weights, and spacing densities.
3. Elevation: Identify shadow styles and depths.

3. Proposal Phase

Before writing the CSS, present a Theme Proposal to the user for confirmation.

Attribute	Extracted Value	Source
Primary Color	#HEX	theme.toml / Screenshot
Background	#HEX	Screenshot
Radius	8px	Screenshot
Spacing	Compact	Screenshot

4. Generation Phase

Once confirmed, perform the following actions:

1. Write CSS: Create src/styles/wireframe-{name}.css.
   • Use the compound selector pattern — two blocks, one for light (default) and one for dark. See get_instructions("starspec/fragments/wireframe/theme-selector-pattern") for the exact template.
   • Implement all variables from get_instructions("starspec/fragments/wireframe/theme-variables").
   • Load custom fonts via @import above the variable blocks if [font] keys are present in theme.toml.
2. Register Theme: Add the new theme entry to src/themes.json:
   • { "id": "{name}", "label": "{Label}" }
   • astro.config.ts auto-discovers the CSS file via fs.existsSync() — no manual config change is needed.

5. Verification Phase

1. Run pnpm compile to ensure the registry and compiler are in sync.
2. Run pnpm build (or check for errors in dev) to ensure the new CSS is valid.
3. Confirm the new theme appears in the Header dropdown.