Prototype Scaffolder

Creates page file structure (TSX + SCSS module + manifest entry) in the sandbox mattermost-proto-playground project

SKILL.md

GitHub

Prototype 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-composer for 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 (and layout, navigation). Boilerplate must import only components that appear here.
  • The registration manifest: read src/manifests/prototypes.ts to see the current PrototypeEntry shape and the existing PROTOTYPES array before adding an entry.
  • If src/pages/ already has pages, read one existing page + its .module.scss for 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_name is PascalCase and ends with Page
  • Verify route_path is kebab-case and starts with /
  • Check that src/pages/{page_name}/ does not already exist
  • Check that route_path is not already registered in src/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 BackButton import — 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:

  1. Add an import for the page component at the top
  2. Append a PrototypeEntry to the PROTOTYPES array. Match the existing fields exactly — at time of writing these are id, label, path, component, group, optional description, addedAt (ISO YYYY-MM-DD), and optional isPrimary. Use the input page_title as label.
  3. Routes follow the pattern /prototypes/{route-slug}, where {route-slug} is route_path with its leading / stripped — i.e. the manifest entry's path field is /prototypes + route_path (input /channel-settings → path /prototypes/channel-settings). Never write route_path verbatim 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 vertically
  • split-panel: Flex container with .sidebar (240px) and .main (flex: 1) divs
  • tabbed: 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:

  1. All file paths are correct and follow the naming convention
  2. All imports use the @/ alias (not relative ../)
  3. CSS module classnames match between TSX and SCSS
  4. Route path does not collide with existing routes
  5. 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