For cases where you can’t or don’t want to use Supernova Analyze (recommended).
The following is a reference of best practices on how to structure and write instructions for any component-container-template project to make sure your team can get the best results when prototyping with your component library.
- We will cover the three main AI instruction file structures, as well as give prompt and examples from our own design system’s guidelines, these files are:
├── src/
├── supernova/
│ ├── usage.md # ✅ Agent rules for the codebase (framework, UI lib, code style)
│ ├── components.md # ✅ Index of components and how to find each component’s doc
│ ├── icons.md # Icon set reference (if you use an icon library)
│ └── components/ # ✅ Per-component docs (e.g. Accordion.md, Button.md)
- You can adapt this to your own design system component container and follow this setup as a reference of a structure we know works well.
We recommend having your AI agent of choice generate these instructions. Copy the example prompts and run them in your IDE from your template project.
How to write usage.md instructions
What goes into the usage.md doc?
- This file contains agent rules for the whole codebase: how to write components, templates, and state in this project (framework patterns the AI must follow)
- It documents framework basics: component style (e.g. SFCs, standalone, or hooks), template syntax, data binding, and where shared logic lives (composables, services, or hooks), with short code examples
- If you use a UI library, document how to import components, common usage (buttons, forms, feedback, icons), and where the theme is configured; you can reference supernova/icons.md for icons
- Include code style (naming, TypeScript, styling), a brief file structure (e.g. src/ tree), and important notes: which file is the target for AI-generated code and a few must-dos (framework rules, UI library setup, app-level config)
- Keep the file at supernova/usage.md so tooling and agents can find it; it works together with components.md and per-component docs for detailed component usage.
Sample usage.md prompt
Here is a sample prompt you can run to set it up with you IDE’s coding agent of choice:
Create a `supernova/usage.md` file for this project that will be used as agent rules when generating or editing code. The file should instruct the AI to follow our stack and conventions so generated code is consistent and correct.
**Project context (fill in):**
- Framework: [e.g. Vue 3, React, Angular 17+]
- UI library: [e.g. PrimeVue 4, Angular Material, MUI, none]
- Theme or design system: [e.g. Aura from @primeuix/themes, Material theme in styles.scss, custom tokens]
- Entry file where AI-generated UI should go: [e.g. App.vue, app.component.ts, app.tsx]
- Any other critical libraries: [e.g. Vue Router, Pinia, React Query, RxJS]
**Required structure for usage.md:**
1. **Title and intro**
- Start with: "# Supernova Agent Rules" and "When using the codebase, follow these rules:"
2. **[Framework] basics**
- How to write components (e.g. SFCs with `<script setup>`, standalone components, function components with hooks).
- Preferred template/JSX syntax (e.g. v-if/v-for, @if/@for, conditional rendering patterns).
- Data binding and state (e.g. ref/reactive, signals, useState).
- Where to put shared logic (composables, hooks, services, inject()).
- Include 1–2 short code examples for the main patterns.
3. **UI library (if used)**
- How to import components (per-component imports vs barrel imports).
- List the most used components with minimal usage snippets: buttons, cards, form inputs, feedback (messages/toast), icons.
- How icons work (e.g. PrimeIcons class names, mat-icon, icon component).
- Where theme is configured and that it should not be changed unless required.
- Reference `supernova/icons.md` if that file exists.
4. **Code style**
- Naming: components, files, services/hooks/composables, selectors if relevant.
- TypeScript: strict typing, interfaces, avoid `any`, prefer const.
- Styling: scoped styles, layout (flex/grid), spacing (e.g. gap), theming (e.g. CSS variables).
5. **File structure**
- A short tree of `src/` showing: entry component, main config, global styles, components/, services/, lib/ (or equivalent), and a one-line comment for the file where AI should generate code.
6. **Important notes**
- Numbered list of 5–7 critical reminders, including:
- Where AI-generated code should be placed (the entry file above).
- One or two framework-specific must-dos (e.g. "Use Composition API only", "Use standalone components only", "Use hooks only").
- One or two UI library must-dos (e.g. how to import components, how to use toast/icons).
- Any app-level setup that must exist (e.g. Toast in App.vue, provideAnimations(), Zone.js).
Write the content in Markdown with clear headings and short code blocks. Match the tone and level of detail of a “Supernova Agent Rules” usage doc: concise, rule-oriented, with copy-pasteable examples for the stack we actually use in this repo.
How to use this prompt:
- Fill in the bracketed bits (framework, UI library, entry file, theme, critical libs)
- Run the prompt in the project (so the AI can read package.json, main.ts/main.tsx, and key components)
- Review and tweak the generated supernova/usage.md (add project-specific rules or remove unused UI components)
- Keep supernova/icons.md in sync if they reference it from usage.md.
How to write components.md instructions
What goes into the components.md doc?
- The file contains general rules for components (where to import from, any universal rules applicable to all components)
- The file mentions how to get to specific component documentation knowing a component name
- A comprehensive list of component names available in the package
- Make sure that each component has an individual markdown file with doc
- For example, if I have an Accordion component, I should have supernova/components/Accordion.md file
- We cover how to structure and where to locate these specific component information files later
Sample components.md prompt
Create (or update) the file `supernova/components.md`. This file tells AI agents how to find and use component docs in this project. Use the structure below and fill in the placeholders.
**Structure to follow:**
1. **Intro for AI agents**
- Heading: `## For AI Agents`
- Short intro: "When you need detailed information about a specific **[Design System Name]** component:"
- Replace **[Design System Name]** with our design system or product name.
2. **Discovery steps (numbered list)**
- **Step 1:** "First, check if the component exists" → bullet: "See the list of available components below."
- **Step 2:** "Read the component documentation file" → bullet: "Located at `supernova/components/{ComponentName}.md`". Then a sub-list of what each file includes: what the component is for, usage examples, props/API table, known limitations or gotchas.
- **Step 3 (optional):** "For additional examples, check the component's story file (if available)" → bullet: "Located at `supernova/stories/{ComponentPath}/{ComponentName}.stories.[js|ts|tsx]`". Sub-bullets: story files show different states, edge cases, realistic usage; **Important**: ignore `Example`, `Example.Item`, and other demo-only wrappers—focus only on the actual component usage.
- If we don't use Storybook or story files, omit Step 3.
3. **Horizontal rule**
- `---`
4. **Available components**
- Heading: `## Available Components`
- One bullet per documented component: `- **{ComponentName}** – \`supernova/components/{ComponentName}.md\``
- List every component that has (or will have) a doc file under `supernova/components/`. Sort alphabetically or by category if we have one.
Add a short HTML comment at the top: "Use this file to explain how components should be discovered and used by AI agent". Use the same comment style for the Design System Name placeholder. Output only the markdown file content.
**Context (fill in):**
- Design system / product name: **[Design System Name]**
- Do we have Storybook or story files? [Yes / No]. If yes, story path pattern: [e.g. `supernova/stories/...` or `src/stories/...`]
- List of component names that have docs (or "generate from existing files in supernova/components/"): **[e.g. Button, DropdownMenu, Actionable — or "scan supernova/components/ folder"]**
How to use this prompt
- Replace [Design System Name] with your system or product name
- Set whether you use Storybook/stories and the path pattern; remove Step 3 if you don’t
- Either list the component names or ask the AI to scan supernova/components/ and list every *.md file
- Run the prompt in the repo so the AI can see supernova/components/ (and optionally supernova/stories/)
Example of components.md content
The following example is from the instructions we have for components.md file for our own design system container, use it as a reference to write your own.
`📁 supernova / components.md`
## **Dark Matter Components Documentation**
### **For AI Agents**
When you need detailed information about a specific Dark Matter component:
1. **First, check if the component exists** in the list of available components below
2. **Read the component's documentation file** in `supernova/components/{ComponentName}.md` (if available)
- Each component file contains usage examples, props tables, and gotchas
3. **For additional code examples**, check the component's story file in `supernova/stories/{ComponentPath}/{ComponentName}.stories.tsx` (if available)
- Story files contain comprehensive usage examples and various component states
- **Important**: When reading story files, ignore `<Example>` and `<Example.Item>` wrapper components - these are only for Storybook display purposes and should not be used in your code
- Focus on the actual component usage inside these wrappers
## **Available Components**
The following components have detailed documentation in the `supernova/components/` directory:
- **Actionable** - `supernova/components/Actionable.md`
- **Button** - `supernova/components/Button.md`
- **DropdownMenu** - `supernova/components/DropdownMenu.md`
*… list of components goes on…*
How to write specific-component-info.md instructions
What goes into the specific-component-info.md doc?
- Outlines specific documentation per component
- Mentions a usage example, props table, any specific guidelines
- In the root supernova folder create a components folder with instructions for each of your components to instruct the LLM on how to best use them
- The LLM references components.md file first and uses it to be directed to read the individual component’s documentation
Note: we are working on a more automated and maintainable way to do this process in the future, but for now these need to be added by your team. We advise to use an AI agent to help with this process :)
Sample specific-component-info.md prompt
Create (or update) the file `supernova/components/{ComponentName}.md` for the **{ComponentName}** component. Use this exact structure and fill it with accurate information about the component.
**Structure to follow:**
1. **Title**
- Single heading: `## **{ComponentName}**`
- Optional short line under it explaining what the component does.
2. **Description**
- Under `### **Description**`: what problem it solves and when to use it (1–3 sentences).
3. **Anatomy (public API)**
- Under `### **Anatomy (public API)**`: one concrete example of intended usage in a fenced code block (e.g. TSX/JSX or the framework we use). Show the component with real props and optional children/comments (e.g. `{/* Content goes here */}`).
4. **API**
- Under `### API`: a markdown table for **{ComponentName}** with columns: **Prop** | **Type** | **Default** | **Description**.
- Include every public prop (and `children` if it has slot/content).
- If you have access to the component source or JSDoc, use it to fill types, defaults, and descriptions; otherwise infer from usage and docs.
5. **Good to know / Gotchas** (optional)
- Under `### Good to know / Gotchas`: bullet list of important behavior, caveats, or tips (e.g. controlled vs uncontrolled, accessibility, visual quirks). Omit this section if there’s nothing notable.
Use `---` as a horizontal rule between the Anatomy and API sections. Output only the markdown file content, no extra commentary.
**Context (fill in):**
- Component name: **{ComponentName}**
- Source: [e.g. our design system, PrimeVue, Angular Material, internal component at `src/components/Button.tsx`]
- Framework: [e.g. React, Vue, Angular]
How to use this prompt
- Replace every {ComponentName} with the real name (e.g. Button, Accordion)
- Fill in the Context line (source and framework)
- Run the prompt in the repo so the AI can read the component file and JSDoc if needed
- Paste the output into supernova/components/{ComponentName}.md.
Example of DMCollapsible.md content
→ The following example is from the instructions we have for DMCollapsible component in our own design system, use it as a reference to write your own.
`📁 supernova / components / DMCollapsible.md`
## **DMCollapsible**
### **Description**
Collapsible section with a built-in trigger and content area.
### **Anatomy (public API)**
```
<DMCollapsible title="Advanced settings" defaultOpen>
<div>Content goes here</div>
</DMCollapsible>
```
### **API**
**DMCollapsible**
| **Prop** | **Type** | **Default** | **Description** |
| --- | --- | --- | --- |
| title | string | - | Header text shown in the trigger. |
| open | boolean | - | Controlled open state. |
| defaultOpen | boolean | - | Uncontrolled initial open state. |
| onOpenChange | (open: boolean) => void | - | Called when open state changes. |
| showDivider | boolean | false | Show a divider after the trigger. |
| contentClassName | string | - | Additional class names for the content container. |
| className | string | - | Additional class names for the root container. |
| children | React.ReactNode | - | Collapsible content. |
| | | | |
### **Good to know / Gotchas**
- Use `open` with `onOpenChange` for controlled usage, or `defaultOpen` for uncontrolled usage.
- `showDivider` adds a divider line to the trigger row.