Skip to content

Commit 82bece4

Browse files
unthinkmediaunthinkmedia
authored
Initial commit
0 parents  commit 82bece4

138 files changed

Lines changed: 17620 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/copilot-instructions.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Copilot Instructions — Azure Builder Playground
2+
3+
## Pre-Flight Checks
4+
5+
Before doing any work on the user's first prompt, run these checks silently and fix anything missing:
6+
7+
### 1. Dependencies
8+
Check if `node_modules/` exists. If not, run `npm install` automatically.
9+
10+
### 2. Dev Server
11+
Check if the Vite dev server is running (port 5173). If not, start it with `npm run dev` in a background terminal.
12+
13+
### 3. Experiment Metadata
14+
Check if `experiment.json` still has the default placeholder values (`"My Experiment"` / `"A playground for rapid prototyping"`). If so, infer a name and description from the user's first prompt and update the file automatically. For example:
15+
- "Build me a VM overview page" → `{ "name": "Virtual Machine Overview", "description": "Azure VM resource overview page prototype" }`
16+
- "Create a storage account browse page" → `{ "name": "Storage Account Browser", "description": "Browse and manage storage accounts" }`
17+
18+
### 4. Storybook MCP (Mandatory)
19+
Storybook MCP is the primary documentation and discovery source for Azure Portal components. Before building any page or UI:
20+
1. Verify Storybook MCP is running by calling `getComponentList`.
21+
2. If it's not available, stop and tell the user (see below).
22+
3. Call `getComponentsProps` for every component you plan to use — **read the Storybook documentation first** to understand props, variants, usage patterns, and best practices before writing any code. This is especially important for greenfield builds and when modifying existing designs.
23+
4. Import components **and themes** from `@azure-fluent-storybook/components` (an npm package already in the project's dependencies). Both components and themes are exported from this single package.
24+
5. Only drop to raw `@fluentui/react-components` for elements that have no equivalent in `@azure-fluent-storybook/components`.
25+
26+
### 5. MCP Server Availability
27+
If you attempt to use Storybook MCP tools and they aren't available, tell the user:
28+
> "The Storybook MCP server isn't running. Open the Command Palette (`Cmd+Shift+P`), type **MCP: List Servers**, and click **Start** next to **storybook**."
29+
30+
If you attempt to use Playwright MCP tools and they aren't available, tell the user:
31+
> "The Playwright MCP server isn't running. Open the Command Palette (`Cmd+Shift+P`), type **MCP: List Servers**, and click **Start** next to **playwright**."
32+
33+
If the user's prompt involves a Figma URL or mentions Figma and the Figma MCP tools aren't available, tell the user:
34+
> "The Figma MCP server isn't running. Open the Command Palette (`Cmd+Shift+P`), type **MCP: List Servers**, and click **Start** next to **figma**. You'll need a Figma API key — get one at figma.com/developers."
35+
36+
### 6. Page Creation Gate
37+
When the user asks to "make this", "build this", "create a page", or provides a screenshot of a UI to recreate:
38+
1. **STOP** — do NOT write any `.tsx` file directly.
39+
2. Read the page-builder skill at `.github/skills/page-builder/SKILL.md`.
40+
3. Follow its full pipeline: generate `.schema.json` first, validate it, then generate the component.
41+
4. Skipping the schema step is never acceptable.
42+
43+
**WRONG — never do this:**
44+
```
45+
User: "Build me a VM overview page"
46+
Agent: *immediately creates src/main/index.tsx with hand-written JSX*
47+
```
48+
```
49+
User: "Make this" (attaches screenshot)
50+
Agent: *writes a .tsx file without producing a .schema.json first*
51+
```
52+
```
53+
User: "Create a storage account page"
54+
Agent: *generates .schema.json but skips validation and jumps straight to .tsx*
55+
```
56+
57+
**RIGHT — always do this:**
58+
```
59+
User: "Build me a VM overview page"
60+
Agent:
61+
1. Reads .github/skills/page-builder/SKILL.md
62+
2. Queries Storybook MCP for component APIs
63+
3. Reads references/fluent-icon-reference.md for verified icon names
64+
4. Creates VmOverview.schema.json (using only verified icon names)
65+
5. Runs `python pipeline.py VmOverview.schema.json --validate-only` (catches bad icons)
66+
6. Generates VmOverview.tsx from the validated schema
67+
7. Runs page-review skill (token audit → component audit → visual analysis)
68+
8. Fixes all High-priority findings before presenting to user
69+
```
70+
71+
**Icon naming:** Fluent icons use compound names — never invent simple names like `Preview`, `Feedback`, `Refresh`. Always consult `.github/skills/page-builder/references/fluent-icon-reference.md`.
72+
73+
## Workspace Conventions
74+
75+
- Each repo is a single experiment with one `src/main/` and optional `src/variations/`
76+
- The shell (`src/shell/App.tsx`) auto-discovers all versions via `import.meta.glob` — never manually register pages
77+
- **Storybook-first**: Before writing any component code, call `getComponentList` and `getComponentsProps` from Storybook MCP. **Read the Storybook docs for each component** to understand its API, variants, best practices, and gotchas — then import the component from `@azure-fluent-storybook/components`. Use composed/template components (PageHeader, CommandBar, FilterBar, DataGrid, SideNavigation, Azure Container, Resource List Page, etc.) instead of building from raw Fluent primitives. Only drop to raw `@fluentui/react-components` for elements that have no Storybook equivalent.
78+
- **Component imports**: `@azure-fluent-storybook/components` for shared Azure Portal components **and** themes — this is a real npm package installed via `package.json`
79+
- Use `@fluentui/react-components` for UI primitives and `makeStyles` + `tokens` for styling
80+
- Never hardcode colors, fonts, or spacing — always use Fluent tokens
81+
- Variation names use kebab-case
82+
83+
## Azure URL Handling
84+
85+
When the user's prompt contains an Azure Portal URL (anything matching `portal.azure.com`, `azure.microsoft.com`, or similar Microsoft domains):
86+
87+
### Why Playwright, not VS Code's browser
88+
VS Code's integrated browser blocks authentication flows from Microsoft/Entra ID accounts. Azure Portal pages require sign-in, so the built-in browser will fail. **Always use Playwright** to open Azure URLs.
89+
90+
### Procedure
91+
1. **Launch Playwright in headed (non-headless) mode** so the user can see the browser window and authenticate.
92+
2. Navigate to the Azure URL.
93+
3. **Pause and tell the user:**
94+
> "A browser window has opened. Please sign in with your Azure account. Let me know once you're on the page you want me to capture."
95+
4. **Wait for the user to confirm** they've signed in and the page has loaded.
96+
5. Take a screenshot and/or snapshot of the page to use as the design reference.
97+
6. Close the browser or keep it open if the user needs to navigate to additional pages.
98+
99+
### Important
100+
- **Never** attempt to open Azure URLs in VS Code's integrated browser or an iframe.
101+
- **Never** try to automate the Microsoft login flow — let the user authenticate manually in the headed browser.
102+
- If Playwright MCP is not running, prompt the user to start it before proceeding.
103+
- The user may need to navigate through the portal (click into a resource, switch tabs) before the page is ready to capture — wait for their confirmation.

‎.github/skills/.skill-organizer.manifest.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"managedFolders": [
3+
"skill-creator"
4+
],
5+
"manualFolders": [
6+
"component-audit",
7+
"deploy-to-hub",
8+
"experiment-helper",
9+
"iconcloud-browser",
10+
"page-builder",
11+
"page-review"
12+
]
13+
}

‎.github/skills/component-audit/SKILL.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
name: component-audit
3+
description: >
4+
Audit page files to find custom UI elements that could be replaced with existing shared
5+
components from the AzureStorybook library or Fluent UI. Use this skill whenever the user
6+
asks to "audit components", "find custom components", "check for missing shared components",
7+
"what components am I not using from storybook", or after building/editing a page to verify
8+
nothing was re-invented. Also use when the user says "component check", "storybook audit",
9+
or "what did I build that already exists".
10+
---
11+
12+
# Component Audit
13+
14+
Scan page `.tsx` files for custom HTML/CSS patterns that duplicate functionality already
15+
provided by the **@azure-fluent-storybook/components** shared component library or **Fluent UI v9**. The goal
16+
is to surface every piece of hand-rolled UI that has a ready-made replacement so the
17+
developer can decide whether to swap it in.
18+
19+
## When to run
20+
21+
- After building or significantly editing a page (post-build review step)
22+
- On demand when the user asks to check component coverage
23+
- As part of a broader UI verification pass
24+
25+
## How it works
26+
27+
### Step 1 — Load the component registry
28+
29+
Read the AzureStorybook component registry to get the authoritative list of shared
30+
components and their capabilities. Call `getComponentList` and `getComponentsProps` from
31+
Storybook MCP to get the latest component information.
32+
33+
Also reference the component catalog doc for props and usage patterns:
34+
35+
```
36+
.github/skills/page-builder/references/component-catalog.md
37+
```
38+
39+
### Step 2 — Read the target page file(s)
40+
41+
If the user specifies a file, audit that file. Otherwise, audit all `.tsx` files under
42+
`src/pages/`.
43+
44+
For each file, extract:
45+
1. **Imports** — which `@azure-fluent-storybook/components` and `@fluentui/react-components`
46+
are already being used
47+
2. **Style definitions** — all keys inside `makeStyles({...})`
48+
3. **JSX markup** — the rendered component tree
49+
50+
### Step 3 — Detect custom UI patterns
51+
52+
Look for these categories of re-invention:
53+
54+
#### A. Custom HTML elements that map to shared components
55+
56+
| Custom pattern | Likely replacement |
57+
|---|---|
58+
| `<button>` with icon + label styled as a card | `CardButton` |
59+
| `<nav>` or `<div>` with list of links/items | `SideNavigation` |
60+
| `<div>` with key-value pairs in two columns | `EssentialsPanel` |
61+
| `<div>` acting as a toolbar with icon buttons | `CommandBar` |
62+
| `<div>` styled as breadcrumbs with `>` separators | `AzureBreadcrumb` |
63+
| `<div>` with title + icon + pin/star/more actions | `PageHeader` / `PageTitleBar` |
64+
| `<div>` styled as tabs with click handlers | `PageTabs` (or Fluent `TabList`) |
65+
| `<div>` styled as a tag/chip/pill | `FilterPill` (or Fluent `Badge`) |
66+
| `<div>` styled as a step wizard | `WizardNav` |
67+
| `<div>` styled as a flyout/panel overlay | `ServiceFlyout` (or Fluent `Dialog`) |
68+
| `<div>` with metric/status card layout | `HealthStatusCard` |
69+
| `<div>` with "no data" illustration + message | `NullState` |
70+
| `<div>` with search box + hero banner | `SearchBanner` |
71+
| `<img>` loading from `public/azure-icons/` directly | `AzureServiceIcon` |
72+
73+
#### B. Custom styles that duplicate Fluent UI capabilities
74+
75+
| Custom style pattern | Likely replacement |
76+
|---|---|
77+
| Hardcoded `color`, `background-color` hex values | Fluent `tokens.*` |
78+
| Hardcoded `font-size`, `font-weight` values | Fluent typography tokens |
79+
| Custom `box-shadow` values | Fluent shadow tokens |
80+
| Custom border-radius values | Fluent `tokens.borderRadius*` |
81+
| Manual `display: grid/flex` for data tables | Fluent `DataGrid` |
82+
| Manual `display: flex` toggle/switch | Fluent `Switch` |
83+
| Custom `<input>` styling | Fluent `Input` / `Field` |
84+
| Custom `<a>` link styling | Fluent `Link` |
85+
86+
#### C. Inline styles on shared components
87+
88+
Look for `style={{...}}` props applied to shared components that override their
89+
built-in styling. These often indicate the component isn't being used correctly, or
90+
that a variant/prop exists for the desired behavior.
91+
92+
### Step 4 — Generate the audit report
93+
94+
Output a structured report in this format:
95+
96+
```
97+
# Component Audit Report — [FileName]
98+
99+
## Summary
100+
- Components from Storybook: N used
101+
- Custom UI patterns found: N
102+
- Potential replacements: N
103+
104+
## Custom Patterns Found
105+
106+
### 1. [Description of custom element]
107+
- **Location:** Lines X–Y
108+
- **What it does:** [brief description]
109+
- **Suggested replacement:** `ComponentName` from `@azure-fluent-storybook/components`
110+
- **Confidence:** High / Medium / Low
111+
- **Notes:** [why this is or isn't a clear swap]
112+
113+
### 2. [Next pattern]
114+
...
115+
116+
## Already Using (✓)
117+
- `AzureGlobalHeader` — top nav
118+
- `CardButton` — service shortcuts
119+
- ...
120+
121+
## Not Applicable
122+
List any Storybook components that exist but aren't relevant for this page type
123+
(e.g., `WizardNav` isn't needed on a home page).
124+
```
125+
126+
### Confidence levels
127+
128+
- **High** — The custom markup is a near-exact replica of what the shared component
129+
renders. Straightforward swap.
130+
- **Medium** — The custom markup serves the same purpose but has minor differences
131+
(extra props, different layout). Would require checking the shared component's props
132+
to confirm feasibility.
133+
- **Low** — The custom markup is in the same "family" but may be intentionally
134+
different. Flagged for awareness rather than as a hard recommendation.
135+
136+
## Important constraints
137+
138+
- Do NOT modify any files — this skill is read-only / diagnostic
139+
- Do NOT suggest replacements that would lose functionality the custom code has
140+
- Fluent UI v9 components (`@fluentui/react-components`) are also valid — not
141+
everything needs to come from AzureStorybook
142+
- AzureStorybook wraps Fluent in many cases, so prefer AzureStorybook when both exist
143+
(e.g., prefer `PageTabs` over raw `TabList` if `PageTabs` covers the use case)
144+
- If a custom component is genuinely novel (no shared equivalent exists), say so
145+
explicitly and suggest it as a candidate for extraction into AzureStorybook

‎.github/skills/deploy-to-hub/SKILL.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
name: deploy-to-hub
3+
description: >
4+
Deploy, share, or send the current experiment to Azure Builder Hub.
5+
Triggers when the user says "deploy this", "deploy to hub", "share this",
6+
"send this", "send to hub", "publish this", "push to hub", or similar phrases.
7+
---
8+
9+
# Deploy to Hub Skill
10+
11+
Deploy the current experiment from the Playground sandbox to Azure Builder Hub so it appears in the gallery for other Microsoft employees.
12+
13+
**Zero-config** — authenticates via your existing `az login` session. No keys, secrets, or `.env` files needed.
14+
15+
## When to Use
16+
17+
This skill triggers on any of these user intents:
18+
- "Deploy this" / "Deploy to hub" / "Deploy my experiment"
19+
- "Share this" / "Share to hub"
20+
- "Send this" / "Send to hub"
21+
- "Publish this to hub"
22+
- "Push to hub"
23+
24+
## Prerequisites
25+
26+
The user must be logged in to Azure CLI (`az login`). If they haven't, the deploy script will print clear instructions. No keys or secrets are needed — just a Microsoft account.
27+
28+
## Step-by-Step Workflow
29+
30+
### Step 1: Pre-Flight Check
31+
32+
1. Check that `experiment.json` has been updated from default values. If it still says `"My Experiment"` / `"A playground for rapid prototyping"`, infer a name and description from the user's work, then update it.
33+
2. Run `npm install` if `node_modules/` doesn't exist.
34+
3. Check `az account show` works. If not, tell the user to run `az login` first.
35+
36+
### Step 2: Deploy
37+
38+
Run the deploy script:
39+
40+
```bash
41+
npm run deploy
42+
```
43+
44+
If the user wants to skip thumbnail generation (faster deploy), use:
45+
46+
```bash
47+
npm run deploy:quick
48+
```
49+
50+
### Step 3: Report
51+
52+
After the script completes, extract the output and tell the user:
53+
54+
- The project ID
55+
- The version number
56+
- The Hub URL where they can view it
57+
- The preview URL
58+
59+
Example output:
60+
> "Your experiment has been deployed to Hub as project `abc123` (version 2).
61+
> View it at: https://victorious-ocean-0ea8ca710.5.azurestaticapps.net/project/abc123
62+
> Preview: https://victorious-ocean-0ea8ca710.5.azurestaticapps.net/api/projects/abc123/preview/"
63+
64+
## Flags
65+
66+
| Flag | Effect |
67+
|------|--------|
68+
| `--skip-thumbnail` | Skip Playwright thumbnail generation (faster) |
69+
| `--skip-build` | Skip `npm run build` (use existing dist/) |
70+
71+
## Troubleshooting
72+
73+
| Error | Fix |
74+
|-------|-----|
75+
| `deploy.config.json not found` | You must be in the project root |
76+
| `Not logged in to Azure` | Run `az login` then try again |
77+
| `experiment.json not found` | You must be in the project root |
78+
| `Hub registration failed (401)` | Your Azure account may not be in the allowed tenant. Verify with `az account show`. |
79+
| `Thumbnail generation failed` | Use `--skip-thumbnail` or install Playwright: `npx playwright install chromium` |

0 commit comments

Comments
 (0)