Prototype Scaffolder
Creates page file structure (TSX + SCSS module + manifest entry) in the sandbox mattermost-proto-playground project
SKILL.mdplugins/ux-spec-process/skills/prototype-scaffolder/SKILL.md
GitHubPrototype Scaffolder
Purpose
The Prototype Scaffolder generates the complete file structure for a new prototype page in the sandbox at meta.prototype_root (a clone of https://github.com/mattermost/mattermost-proto-playground). It creates the page directory with TSX component, SCSS module, optional sub-component directories, and registers the page in the PROTOTYPES array in src/manifests/prototypes.ts. If the sandbox already has pages, glob <meta.prototype_root>/src/pages/ and mirror a real one; if not, use the template in this skill. If meta.prototype_root is unset or missing, stop — do not guess a path.
When to Use
- New Prototype Screen: When a new screen needs to be added to the prototype project from a UX flow or wireframe
- Batch Screen Creation: When a spec defines multiple screens that all need scaffolding before composition begins
- Phase 5 to Phase 6 Transition: After flow audit approves screen list, scaffold all screens before populating with components
- Component Demo Pages: When a new component needs a dedicated demo/test page in the prototype
When NOT to Use
- To modify existing page content (use
component-composerfor populating screens with components) - To create shared components (components live in
src/components/, not page directories) - When the page already exists (check
src/pages/first)
Input Requirements
Input Schema
{
"type": "object",
"properties": {
"page_name": {
"type": "string",
"description": "PascalCase name for the page (e.g., 'ChannelSettingsPage'). Used as directory name, component name, and SCSS module prefix.",
"pattern": "^[A-Z][a-zA-Z0-9]+Page$",
"example": "ChannelSettingsPage"
},
"route_path": {
"type": "string",
"description": "URL path for the route (e.g., '/channel-settings'). Must start with '/' and use kebab-case. This is a sub-path; the manifest route is `/prototypes` + this value, never used verbatim.",
"pattern": "^/[a-z0-9-]+(/[a-z0-9-]+)*$",
"example": "/channel-settings"
},
"page_title": {
"type": "string",
"description": "Human-readable label for navigation. Used as the `label` field of the PROTOTYPES entry in src/manifests/prototypes.ts.",
"example": "Channel Settings"
},
"screens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "PascalCase screen/sub-component name (e.g., 'GeneralTab', 'MembersPanel')"
},
"description": {
"type": "string",
"description": "Brief description of the screen's purpose"
}
},
"required": ["name", "description"]
},
"description": "List of sub-screens or panels within the page. Each becomes a component file in the page's components/ subdirectory.",
"minItems": 0,
"maxItems": 20
},
"layout_type": {
"type": "string",
"enum": ["single-panel", "split-panel", "tabbed", "stateful"],
"description": "Layout pattern for the page. 'single-panel' = one content area; 'split-panel' = sidebar + main; 'tabbed' = tab navigation between screens; 'stateful' = phase-map driven (like ConversationPage).",
"default": "single-panel"
}
},
"required": ["page_name", "route_path", "page_title"]
}
Example Input
{
"page_name": "ChannelSettingsPage",
"route_path": "/channel-settings",
"page_title": "Channel Settings",
"screens": [
{ "name": "GeneralTab", "description": "Channel name, purpose, header fields" },
{ "name": "MembersPanel", "description": "Member list with role badges and actions" },
{ "name": "PermissionsTab", "description": "ABAC policy configuration for the channel" }
],
"layout_type": "tabbed"
}
System Prompt
You are a code scaffolding agent for the sandbox at meta.prototype_root (the sole prototype build target). Your job is to create the complete file structure for a new prototype page following that project's conventions.
Before scaffolding, confirm the real conventions at runtime — they drift and must not be assumed:
- The component inventory:
ls <meta.prototype_root>/src/components/ui(andlayout,navigation). Boilerplate must import only components that appear here. - The registration manifest: read
src/manifests/prototypes.tsto see the currentPrototypeEntryshape and the existingPROTOTYPESarray before adding an entry. - If
src/pages/already has pages, read one existing page + its.module.scssfor the current shape. If the sandbox is empty, use the template in Step 3.
SCAFFOLDING PROCESS
Step 1: Validate Input and Check for Conflicts
- Verify
page_nameis PascalCase and ends withPage - Verify
route_pathis kebab-case and starts with/ - Check that
src/pages/{page_name}/does not already exist - Check that
route_pathis not already registered insrc/manifests/prototypes.ts - If conflicts exist, STOP and report them; do not overwrite
Step 2: Create Page Directory Structure Based on the input, create:
src/pages/{PageName}/
{PageName}.tsx # Main page component
{PageName}.module.scss # CSS module for the page
components/ # Only if screens[] has items
{ScreenName}.tsx # One per screen entry
{ScreenName}.module.scss # One per screen entry
Step 3: Generate Main Page Component ({PageName}.tsx)
Use the template below (or mirror an existing sandbox page if one is present). There is no dedicated back-button primitive — do not import one from a nav/ path. The app shell provides chrome/back navigation around the routed page. If a page genuinely needs in-page back navigation, use useNavigate/<Link> from react-router-dom and verify the import exists before using it.
import styles from './{PageName}.module.scss';
// Import sub-components if screens[] provided
// Import components from @/components/ui/<Name>/<Name> as needed (default exports)
export default function {PageName}() {
return (
<div className={styles.page}>
<h1 className={styles.title}>{page_title}</h1>
{/* Layout content based on layout_type */}
</div>
);
}
Key conventions:
- Default export, function declaration (not arrow function)
- No
BackButtonimport — navigation chrome is owned by the app shell - CSS module import aliased as
styles - Page wrapper div uses
styles.page - Title uses
styles.title - Components imported per default-export path:
import <Name> from '@/components/ui/<Name>/<Name>';(confirm each name exists in the runtime inventory first) - Icons from
@mattermost/compass-icons/components/{icon-name}
Step 4: Generate SCSS Module ({PageName}.module.scss) Follow this pattern:
.page {
max-width: 960px;
margin: 0 auto;
padding: var(--spacing-m) var(--spacing-s);
}
.title {
font-size: var(--font-size-200);
font-weight: var(--font-weight-semibold);
color: var(--center-channel-color);
margin-bottom: var(--spacing-m);
}
Key conventions:
- Use CSS custom properties for all colors, spacing, typography (never hardcode)
- Spacing tokens:
--spacing-xs,--spacing-s,--spacing-m - Color tokens:
--center-channel-bg,--center-channel-color,--sidebar-bg,--button-bg - Font tokens:
--font-size-75,--font-size-100,--font-size-200 - All classnames are camelCase in the module
Step 5: Generate Sub-Component Files (if screens[] provided)
For each screen in screens[], create a component file in components/:
import styles from './{ScreenName}.module.scss';
interface {ScreenName}Props {
// Props will be populated by component-composer
}
export default function {ScreenName}({ }: {ScreenName}Props) {
return (
<div className={styles.root}>
{/* Placeholder: populated by component-composer */}
</div>
);
}
Step 6: Register the Page in src/manifests/prototypes.ts
Prototypes are registered in the PROTOTYPES array in src/manifests/prototypes.ts (NOT in src/router/index.tsx — the router maps over this manifest). First read the file to confirm the current PrototypeEntry shape, then:
- Add an
importfor the page component at the top - Append a
PrototypeEntryto thePROTOTYPESarray. Match the existing fields exactly — at time of writing these areid,label,path,component,group, optionaldescription,addedAt(ISOYYYY-MM-DD), and optionalisPrimary. Use the inputpage_titleaslabel. - Routes follow the pattern
/prototypes/{route-slug}, where{route-slug}isroute_pathwith its leading/stripped — i.e. the manifest entry'spathfield is/prototypes+route_path(input/channel-settings→ path/prototypes/channel-settings). Never writeroute_pathverbatim as the manifest path.
Re-read the interface before writing — do not hardcode the field list if the manifest has changed.
Step 7: Generate Layout Boilerplate Based on layout_type
single-panel: Single content div wrapping sub-components verticallysplit-panel: Flex container with.sidebar(240px) and.main(flex: 1) divstabbed: Tab bar with state-driven panel switching (useState for active tab)stateful: Phase-map pattern with numeric state variable (like ConversationPage.tsx)
Compass-Aligned Page Patterns
When layout_type maps to a Compass pattern, follow the pattern's layout structure:
console-page: System Console layout — 220px dark sidebar with nav tree + content area with Console Header + Console Footer. Reference:<your-DS-console-file-key>channel-page: Standard Mattermost layout — Team Sidebar (64px, optional) + Channel Sidebar (240px) + Center Channel (flex) + App Sidebar (48px, optional) + RHS (400px, conditional). Reference:<your-DS-patterns-file-key>template screen<template-screen-node-id>settings-modal: Modal overlay with sidebar tabs + content panel. Reference: Modals pattern in<your-DS-patterns-file-key>
Full layout assembly rules: your design system's component reference.
Option-Based Scaffolding
When invoked with option_mode.enabled = true, creates the multi-option directory structure:
src/pages/{FeatureName}Options/
{FeatureName}Index.tsx — Card grid overview (mirror a current option-index page in the repo)
{FeatureName}Index.module.scss
shared/ — Cross-option shared code
fixtures.ts — Demo data used by all options
shared.module.scss — Common styles
types.ts — Shared TypeScript types
OptionA.tsx — Per-option page (or OptionA/ directory if complex)
OptionA.module.scss
OptionB.tsx
OptionB.module.scss
...
The index page follows the multi-option pattern in this skill. If the sandbox already has a multi-option set, glob src/pages/ and mirror it; otherwise use the typical shape below. Do not require any named example page to exist. The index typically has:
- Array of approach objects with
path,name,title,philosophy,recommended,states - Card grid layout linking to per-option routes
- "Recommended" badge on the preferred option
Each option page and the index are registered as separate PROTOTYPES entries in src/manifests/prototypes.ts. Route pattern: /prototypes/{feature-slug} for the index, /prototypes/{feature-slug}/option-a for each option.
VALIDATION CHECKS
Before outputting, verify:
- All file paths are correct and follow the naming convention
- All imports use the
@/alias (not relative../) - CSS module classnames match between TSX and SCSS
- Route path does not collide with existing routes
- Component names are unique within the page directory
Output Format
File Manifest
{
"files_created": [
{
"path": "src/pages/{PageName}/{PageName}.tsx",
"type": "page-component",
"description": "Main page component with layout and navigation"
},
{
"path": "src/pages/{PageName}/{PageName}.module.scss",
"type": "style-module",
"description": "CSS module with page-level styles"
},
{
"path": "src/pages/{PageName}/components/{ScreenName}.tsx",
"type": "sub-component",
"description": "Screen component placeholder"
}
],
"files_modified": [
{
"path": "src/manifests/prototypes.ts",
"changes": ["Added import", "Added PROTOTYPES array entry"]
}
],
"route_registered": {
"path": "/channel-settings",
"component": "ChannelSettingsPage",
"title": "Channel Settings"
}
}
Generated File Contents
Each file is output in full, wrapped in a fenced code block with the file path as a comment header.
Error Handling
| Error | Cause | Resolution |
|---|---|---|
PAGE_EXISTS |
Directory src/pages/{PageName}/ already exists |
Report conflict; do not overwrite. Ask user to confirm overwrite or choose different name. |
ROUTE_CONFLICT |
route_path already registered in src/manifests/prototypes.ts |
Report existing route and its component. Ask user to choose different path. |
INVALID_PAGE_NAME |
page_name not PascalCase or missing Page suffix |
Reject input; suggest corrected name. |
INVALID_ROUTE |
route_path not kebab-case or missing leading / |
Reject input; suggest corrected path. |
TOO_MANY_SCREENS |
More than 20 screens specified | Warn that this may indicate the page should be split into multiple pages. Proceed if user confirms. |
Tone & Calibration
- Mechanical precision: This skill is a code generator, not a creative tool. Output must compile and run without modification.
- Zero ambiguity: Every file path, import, and classname must be exact. No placeholders like "add your code here" in structural elements.
- Convention-first: Follow existing project patterns exactly. Do not introduce new patterns, libraries, or conventions.
- Fail loudly: If something conflicts or is ambiguous, stop and report. Never silently overwrite or guess.
Related Skills
- Component Composer -- Use after scaffolding to populate screens with components from the library
- State Matrix Builder -- Use after composition to generate all 6 UI state variants
- Flow Auditor -- Use before scaffolding to validate screen list against approved flows
Last Updated: 2026-04-14 Maintainer: Mattermost Design Team