Templates are full-page UI components that Supernova uses to help AI generate prototypes. In your container project, you can set up templates as full-page starting points for prototypes and use them as needed during prototyping.
This guide explains how to structure your templates and patterns so the CLI can automatically discover and register them, and what to document for users and the AI.
Example of Supernova Prototype UI's app shell.
Template instructions are optional. When you add them, users get a better experience in Supernova Create: their feature prototypes can be dropped into real-looking layouts instead of a blank canvas.
We recommend adding a few of the most common app shells — for example navigation menus, settings-style sections, and focused flows like checkout — so prototypes feel in-context.
Directory structure
Templates and reusable patterns live inside a supernova/ directory at the root of your component container:
├── src/
├── supernova/
│ ├── usage.md
│ ├── components.md
│ ├── icons.md
│ ├── components/
│ └── templates/
│ ├── README.md # Optional: table of all templates with descriptions
│ └── AppShell/ # Template layout example:
│ ├── AppShell.tsx # Main component file — must match folder name
│ ├── thumbnail.png # Optional preview image
│ └── README.md # Optional description
└── patterns/
├── README.md # Optional: table of all patterns with descriptions
├── PromptEditor/
│ ├── PromptEditor.tsx # Main component file — must match folder name
│ ├── mockData.ts
│ └── README.md # Optional description
└── SharePopover/
└── SharePopover.tsx
Each template lives in its own folder with a README (and optional thumbnail).
Conventions
Templates
Templates are full-page starting points you can reuse across your product. Think complete layouts like dashboards, settings pages, checkout flows, or onboarding screens—prebuilt pages you can copy, customize, and prototype on top of fast.
- Each template lives in its own folder under supernova/templates/.
- The folder name is the template identifier (e.g. AppShell).
- The main component file must match the folder name exactly: AppShell/AppShell.tsx (React) or AppShell/AppShell.ts (Angular)
- The display name is derived automatically from the folder name: PortalHome → "Portal Home", AppShell → "App Shell".
Angular templates
Angular templates follow the same folder structure. Key differences:
- The main file extension is .ts instead of .tsx (e.g. AppShell/AppShell.ts).
- The app entry point is src/app.component.ts, where AI-generated code will be placed.
- The component selector must match the folder name and main component file in kebab-case
- Folder: AppShell → File: AppShell/AppShell.ts → Selector: app-shell
- Folder: Dashboard → File: Dashboard/Dashboard.ts → Selector: dashboard
Example with Angular templates repository.
Patterns
Patterns are reusable UI building blocks that appear throughout your product. Think share dialogs, notification modals, prompt windows, chat panels—any ready-made piece of UI you want to drop in as-is and prototype on top of.
- Reusable components shared across templates live under supernova/patterns/.
- Same naming rules apply: folder name matches the main component file.
- Patterns are automatically included in any template that imports them.
Thumbnails
Place a thumbnail image directly inside the template or pattern folder. Supported file names:
- thumbnail.png
- thumbnail.svg
- thumbnail.jpg
- thumbnail.jpeg
Descriptions
The CLI extracts descriptions in this priority order:
-
Individual README.md — first paragraph after the # heading, e.g.
# AppShell
The Portal home page with Create/Ask mode switching. -
Directory-level README.md table — a markdown table in supernova/templates/README.md or supernova/patterns/README.md, e.g.
| Template | Description | - Fallback — if neither is found, a generic description is generated.
Dependency resolution
Dependencies between templates and patterns are detected automatically via TypeScript imports. If AppShell.tsx (or .ts for Angular) imports from ../../patterns/PromptEditor/PromptEditor, the PromptEditor files are automatically included.
Transitive dependencies are resolved automatically. If Template A uses Pattern B, and Pattern B uses Pattern C, all three are included.
What goes into the layout templates setup?
1. Root index: supernova/templates/README.md
Explains that templates are full-page, read-only starting points; that each template lives in its own folder with a README; and that code must be copied to src/components/ (or your equivalent) before editing—never edit files under supernova/ directly.
Include:
- An Available templates table (template name, short description, "use for").
- A Copying templates section: what to copy (e.g. .tsx/.ts/.vue, assets, pattern dependencies), what not to copy (e.g. READMEs), and that imports must be updated after copy.
- A clear note before the copying section: never edit or link to files in supernova/ directly.
2. One folder per template
Each layout is in its own folder under supernova/templates/, e.g. supernova/templates/AppShell/, containing the layout component file(s), optional thumbnail, optional assets/, and a README.md for that template only.
3. Each template README
Per-template documentation so the AI (and users) know what the layout is and how to use it:
- Use for — when to pick this layout.
- Key components — main UI pieces (e.g. ComponentName - brief description).
- Features — behavior and structure (collapsible sections, nav structure, mock data usage, responsive behavior, etc.).
- Mock data — table of data the template expects (columns: Data | Description).
- Files to copy — exact list: which files → where; "Do NOT copy" for READMEs; if there are pattern dependencies, list those files and destinations too.
- Dependencies — if the template imports from supernova/patterns/ or other shared code, list which patterns/files it uses (and include them in "Files to copy").
- Design guidelines (optional) — only if the template has specific layout or visual rules; keep it short.
4. Template code
Layout components are reference-only: no SDK or app logic, only UI and mock data.
Use a consistent structure (e.g. imports → types → mock data → helpers → main exported layout). Mention in the root README that templates use only your design system or library (e.g. "only DM components from @supernovaio/dm").
5. Where templates live
All of this lives under supernova/templates/ (and reusable pieces under supernova/patterns/). The root README is the entry point; the AI should read it first, then open a specific template's README when a user picks a layout.
Uploading Templates through CLI
Update container package.json to surface templates:
Run the following CLI command from the root of your component container to scan the supernova/ directory, resolve all dependencies, and update the supernova.templates section of your package.json automatically:
supernova template-upload --discover
- You can manually edit the generated entries in package.json afterwards — for example to tweak a description or display name.
- Because package.json is in source control, any manual changes are tracked in your diff and won't be lost.
- If you re-run --discover, review the diff before committing to make sure the auto-generated values are what you want.
Discover and upload
To discover and immediately upload to a workspace:
supernova template-upload --discover --workspace-id=<id> --design-system-id=<id>
What gets written to package.json
{
"supernova": {
"templates": {
"Appshell": {
"name": "App Shell",
"description": "A complete Cloud application shell with collapsible dark sidebar and light content area."
}
}
}
}
Uploading without discovery
If you already have supernova.templates configured in your package.json and don't need auto-discovery, you can upload directly:
supernova template-upload --workspace-id=<id> --design-system-id=<id>
This skips discovery entirely and uses whatever is already defined in package.json.
Sample prompts for creating Templates
Prompt 1: Generate the root supernova/templates/README.md
Create (or update) the file `supernova/templates/README.md` for our layout templates. Use this structure:
1. **Title**: "# Templates" and one sentence: templates are full-page layouts as starting points; each template is in its own folder with a README.
2. **Warning**: A clear note that files in this folder must NEVER be modified directly — they are read-only reference code, excluded from the build. Always copy template code to `src/components/` (or our equivalent) before making changes. Add a second short warning before the "Copying" section: never edit or link to files in `supernova/` directly.
3. **Available templates**: A markdown table with columns: Template (link to folder e.g. ./AppShell/), Description, Use for. One row per template we have under `supernova/templates/`. Add a line: "See each template's README.md for detailed documentation."
4. **Copying templates**: Numbered steps: (1) Copy only the files you need to `src/components/` — list what to copy (e.g. component files, assets) and what NOT to copy (e.g. README). (2) If a template has pattern dependencies, copy template + pattern files and update paths. (3) Update import paths after copy. (4) Modify mock data as needed.
5. **Template structure** (optional): A short code block showing the typical order in our template files: imports, types, mock data, helper components, main template export.
6. **Notes**: Bullet list — e.g. templates use only [our design system]; UI-only, no SDK; designed to be copied and modified, not imported directly.
Fill in template names and paths from our actual `supernova/templates/` folder. Output only the markdown.
Prompt 2: Generate one template’s README (supernova/templates/{TemplateName}/README.md)
Create (or update) the file `supernova/templates/{TemplateName}/README.md` for the **{TemplateName}** layout template. Use this structure:
1. **Title**: "# {TemplateName}" and one short sentence describing the layout (e.g. "A complete app shell with collapsible sidebar and content area").
2. **Use for**: Under "## Use for" — 1–2 sentences or a short list of when to use this template (e.g. "Design Systems Platform, dashboards", "Settings pages, configuration UIs").
3. **Key components**: Under "## Key components" — bullet list of the main UI pieces (e.g. "LeftPanel - Collapsible dark sidebar", "Navigation - Primary and secondary nav items"). Use format: `ComponentName` - brief description.
4. **Features**: Under "## Features" — bullet list of behavior and structure (collapsible sections, nav structure, mock data usage, responsive behavior, etc.). Use bold for sub-headings if needed.
5. **Dependencies** (optional): If this template imports from `supernova/patterns/` or other shared code, add "## Dependencies" and list which patterns/files it uses.
6. **Design guidelines** (optional): Only if this template has specific layout or visual rules (e.g. message grouping, connecting lines). Keep it short.
7. **Mock data**: Under "## Mock data" — a markdown table with columns: Data | Description. List every mock entity the template uses (User, Workspace, etc.).
8. **Files to copy**: Under "## Files to copy" — a fenced block (or list) with:
- "Copy:" then each file to copy and destination (e.g. "TemplateName.tsx → src/components/TemplateName.tsx", "assets/foo.json → src/components/assets/foo.json").
- If there are pattern dependencies: "Pattern dependencies (also copy):" and list those files and destinations.
- "Do NOT copy:" then README.md and any other docs.
Use the actual component file(s) in `supernova/templates/{TemplateName}/` to fill in key components, features, mock data, and files. Output only the markdown.
**Context**: Template name: **{TemplateName}**. Framework: [e.g. React, Vue]. Path to template folder: `supernova/templates/{TemplateName}/`.
Prompt 3: Add a new template to the index (after adding a new folder)
We added a new layout template under `supernova/templates/{NewTemplateName}/` (with {NewTemplateName}.tsx and README.md). Update `supernova/templates/README.md`: (1) Add one row to the "Available templates" table for **{NewTemplateName}** with a short description and "use for" cases. (2) If the "Copying templates" or "Template structure" sections need to reflect this template (e.g. new file types or pattern deps), add one sentence or bullet. Do not remove or change existing template rows. Output only the updated README content.
Point the LLM to templates in usage.md
Examples of where you can add this information in the usage.md file:
1. Early in usage.md (e.g. after “Project structure” or “File structure”)
Add a short subsection so the rule is visible when the model is reading instructions:
### Layout templates
Full-page layout starting points live in **`supernova/templates/`**. Each template has its own folder and a README. Templates are **read-only** — never edit files there; always copy to `src/components/` (or your app equivalent) first, then customize.
For the list of available templates and how to copy them, see **`supernova/templates/README.md`** (or **`supernova/templates.md`** if you use a single doc at that path).
2. In “Important notes” or a “Where to find things” / “Source of truth” list at the end of usage.md
Add one line so the model knows where to look when it’s searching for “templates” or “layouts”:
- **Layout templates**: `supernova/templates/README.md` — Full-page layouts to copy into your app (read-only; copy to `src/components/` before editing).