interactive-sites

name

interactive-sites

description

Creates professional, interactive multi-page websites from project documentation using React 18 + TypeScript + Tailwind CSS. Features landing page with hero and KPI cards, dark sidebar navigation, hash-based routing, full trilingual i18n (EN/PT-BR/ES), Microsoft+GitHub logo branding, and end-to-end storytelling. Develops with Vite (hot reload), bundles to single portable HTML via Parcel. USE FOR: create interactive site, project portal, documentation site, interactive dashboard, transform .md deliverables into website, create landing page, build project visualization, interactive architecture site, client-facing web portal. DO NOT USE FOR: FigJam/Mermaid diagrams (use figjam-diagrams), presentations (use pptx-creator), Word documents (use docx-creator), Excel (use xlsx-creator), PDF (use pdf-creator).

Interactive Sites

Create professional, interactive multi-page websites from project documentation. Uses Vite + React 18 + TypeScript + Tailwind CSS for development, bundles to a single portable HTML file via Parcel + html-inline. Every site features Microsoft+GitHub branding, trilingual i18n, dark sidebar navigation, and end-to-end storytelling.

Architecture

Development Mode

npm install && npm run dev

Vite dev server with hot module replacement at localhost:5173. Full React 18 + TypeScript + Tailwind CSS development experience with path aliases (@/).

Production Bundle

bash scripts/bundle.sh

Produces a single self-contained .html file with all JS, CSS, and images inlined. Opens in any browser — no server, no build step, no Node.js needed by the viewer.

Stack

Layer	Technology	Purpose
Framework	React 18	Component-based UI
Language	TypeScript (strict)	Type safety, i18n enforcement
Styling	Tailwind CSS 3.4	Utility-first CSS with Microsoft tokens
Dev server	Vite 6	Fast HMR, path aliases
Bundler	Parcel + html-inline	Single-file HTML output
Routing	useHash() hook	Hash-based, no react-router, works in single HTML
i18n	React Context + tx()	Full trilingual support (EN/PT-BR/ES)
Components	Custom lightweight	No shadcn/ui — under 200KB bundle

Key Decisions

• No shadcn/ui — Custom lightweight components keep bundle under 200KB. shadcn/ui adds 40+ unneeded components and 500KB.
• No react-router — Hash-based routing via useHash() hook works in single HTML file without a server.
• Base64 logos — Images embedded as data URIs by default for full portability. --no-inline-images flag for workspace-local relative paths.

Project Structure

The template lives at .github/skills/interactive-sites/template/. The agent clones it to output/html/{project-slug}/ per project.

template/
├── package.json                    # Dependencies: React 18, Vite, Tailwind, Parcel
├── tsconfig.json                   # TypeScript strict, @/ path alias
├── vite.config.ts                  # Vite config with @/ alias, ./ base
├── tailwind.config.ts              # Microsoft palette as Tailwind tokens
├── postcss.config.js               # Tailwind processing
├── index.html                      # Entry HTML
├── public/
│   └── logos/                      # Copy MS+GH and client logos here
├── scripts/
│   └── bundle.sh                   # Parcel → html-inline → single HTML
└── src/
    ├── main.tsx                    # React 18 createRoot
    ├── App.tsx                     # Shell: Header + Sidebar + Router + Footer
    ├── i18n.tsx                    # tx() helper + LangContext + T translations
    ├── types.ts                   # Shared TypeScript interfaces
    ├── hooks/
    │   └── useHash.ts             # Hash-based routing hook
    ├── components/
    │   ├── Header.tsx             # MS+GH logo left, client center, lang selector right
    │   ├── Sidebar.tsx            # Dark sidebar, collapsible, section icons
    │   ├── Footer.tsx             # Logos + version + confidential
    │   ├── LangSelector.tsx       # EN / PT-BR / ES dropdown
    │   ├── Card.tsx               # Content card with hover lift
    │   ├── Table.tsx              # Sortable table with sticky header
    │   ├── Annotation.tsx         # Info / Success / Warning / Critical boxes
    │   ├── KpiCard.tsx            # Metric card (value + label + trend)
    │   ├── ExpandableSection.tsx  # Click-to-expand panel
    │   ├── FlowDiagram.tsx        # SVG flow with nodes + arrows
    │   ├── Badge.tsx              # Status badges (PRODUCTIVE, IN DEV, DRAFT)
    │   ├── CodeBlock.tsx          # Dark-themed code display with copy
    │   ├── Modal.tsx              # Overlay for detail views
    │   ├── Timeline.tsx          # Gantt-like CSS grid
    │   └── TabGroup.tsx          # Horizontal tabs within a page
    ├── pages/
    │   ├── Landing.tsx            # Hero + KPIs + navigation grid
    │   └── (project pages)        # One component per content section
    └── styles/
        └── globals.css            # Tailwind directives + custom utilities

Logo System

Logo Files

File	Background	Context
logo-msft-github-color.png	Light (#FFF)	Header, landing hero, footer
logo-msft-github-color-black.png	Light (alt)	Header when no white bg
logo-msft-github-white.png	Dark (#1B1B1F)	Sidebar bottom, dark sections
logos/customer/logo-color.png	Light	Header center
logos/customer/logo-white.png	Dark	Dark sections

Header Layout

┌──────────────────────────────────────────────────────────────┐
│ [MS+GH Logo] [Project Name]          [Client Logo]  [EN ▼] │
│              [Client — v1.0.0 — 2026-03-09]                  │
├══════════════════════════════════════════════════════════════╡ ← 4-color bar

• Left: Microsoft+GitHub combined logo + project name + metadata
• Center: Client logo (optional, hidden if not provided)
• Right: Language selector dropdown

Logo Embedding

Default (portable): Logos converted to base64 data URIs by bundle.sh Workspace-local: Use --no-inline-images flag for relative paths: ./logos/logo-msft-github-color.png

Inline SVG Fallback

The Header component includes inline SVG Microsoft 4-window + GitHub Octocat as fallback when no image file is provided. This ensures the header always renders branded logos.

i18n System

tx() Helper Function

export function tx(obj: I18nString, lang: Lang): string {
  if (typeof obj === 'string') return obj;       // Technical term — pass through
  return obj[lang] || obj.en;                     // Localized — resolve by lang
}

I18nString Type

export type I18nString = string | { en: string; pt: string; es: string };

• Plain string = technical term (API, MCP, GitHub, Docker) — stays English everywhere
• Object = user-facing text — must have all 3 translations

Language Context

// Provider wraps the entire App
<LangProvider>
  <AppShell />
</LangProvider>

// Any component can access language
const { lang, setLang } = useLang();

UI Chrome Translations (T constant)

The T constant in i18n.tsx contains translations for navigation labels, buttons, table headers, and other UI chrome. All 3 languages must be complete.

Translation Rules

1. Default language: en (English)
2. All user-facing text must have {en, pt, es} translations
3. Technical terms stay English: API, MCP, GitHub, Docker, Azure, AWS, Foundry, Kubernetes, etc.
4. Agent names stay unchanged: Sabiá, Íris, Aurora, Ary, Operação, Águia (proper nouns)
5. Language selector always visible in header — never hidden
6. Every data constant with translatable fields uses I18nString

Data Layer Pattern

// Example: Agent data with i18n
const AGENTS = [
  {
    id: 'sabia',
    icon: '🐦',
    name: 'Sabiá',                    // Proper noun — plain string
    domain: {                         // User-facing — i18n object
      en: 'Pipeline Diagnostics',
      pt: 'Diagnóstico de Pipelines',
      es: 'Diagnóstico de Pipelines',
    },
    status: 'productive',             // Badge variant — plain string
    phase: 'Phase 1',                 // Technical label — plain string
    description: {
      en: 'Analyzes pipeline failures and suggests fixes...',
      pt: 'Analisa falhas de pipeline e sugere correções...',
      es: 'Analiza fallas de pipeline y sugiere correcciones...',
    },
  },
  // ... more agents
];

Design System

Microsoft Brand Palette (Tailwind tokens)

Token	Hex	Use
ms-red	#F25022	Security, Critical, Blocked
ms-green	#7FBA00	Success, Testing, Approved
ms-blue	#00A4EF	Data, Integration, Cloud
ms-yellow	#FFB900	Planning, Warnings, Events
ms-primary	#0078D4	Headers, CTAs, Primary actions
ms-dark-green	#107C10	Confirmed, Healthy
ms-purple	#5C2D91	AI/Agents, Modernization
ms-orange	#D83B01	Human actions, In Development
ms-teal	#008272	Monitoring, Infrastructure

Neutral Colors

Token	Hex	Use
neutral-text	#323130	Body text
neutral-secondary	#605E5C	Metadata, captions
neutral-bg	#F9F9F9	Page background
neutral-card	#FFFFFF	Cards, panels
neutral-border	#E1DFDD	Card borders
neutral-subtle	#D2D0CE	Dividers

Sidebar Theme

Token	Hex	Use
sidebar-bg	#1B1B1F	Sidebar background
sidebar-hover	#2D2D30	Nav item hover
sidebar-active	#0078D4	Active nav item

Typography

Scale	Size	Weight	Use
text-h1	24px	700	Page titles
text-h2	20px	600	Section headings
text-h3	16px	600	Card titles, subheadings
text-body	14px	400	Body text, table cells
text-meta	12px	400	Metadata, captions, labels
text-tiny	10px	400	Badges, minor labels

Font: Segoe UI (system font stack fallback: Tahoma, Geneva, Verdana, sans-serif).

4-Color Gradient Bar

The Microsoft 4-color bar appears directly under the header. Defined as .ms-gradient-bar in globals.css:

.ms-gradient-bar {
  height: 4px;
  background: linear-gradient(to right,
    #F25022 25%, #7FBA00 25%, #7FBA00 50%,
    #00A4EF 50%, #00A4EF 75%, #FFB900 75%);
}

Design Anti-Patterns (AVOID)

Per Anthropic's frontend-design skill:

• ❌ Inter font (use Segoe UI)
• ❌ Purple gradients on white backgrounds
• ❌ Excessive centered layouts (use left-aligned content)
• ❌ Uniform rounded corners everywhere
• ❌ Generic "AI slop" aesthetics

Component Library

Shell Components

Component	Props	Purpose
Header	meta, onToggleSidebar, logoSrc?, clientLogoSrc?	Top bar with logos, project name, lang selector
Sidebar	items, activePage, onNavigate, isOpen, onClose	Dark nav panel, collapsible
Footer	meta	Bottom bar with logos + confidential
LangSelector	(none — uses context)	Language dropdown

Content Components

Component	Props	Purpose
Card	title?, subtitle?, color?, icon?, onClick?, children	Content card with optional top color bar
Table	columns, rows, className?	Sortable table with sticky header
Annotation	type, children	Info/success/warning/critical callout box
KpiCard	value, label, trend?, color?, lang	Metric card with large value
ExpandableSection	title, icon?, defaultOpen?, children	Click-to-toggle section
FlowDiagram	nodes, connections, lang, onNodeClick?, activeNode?	SVG flow with clickable nodes
Badge	variant, label	Status badge (productive/in-dev/draft/planned)
CodeBlock	code, language?, title?	Dark code display with copy button
Modal	isOpen, onClose, title, children	Overlay detail panel
Timeline	phases, lang	Gantt-like phase grid
TabGroup	tabs, activeTab, onChange, children	Horizontal tabs within page

Page Types

Use the appropriate page type for each content section:

Type	When to Use	Key Components
Landing	Site entry point (always first page)	Hero, KpiCards, navigation Card grid
Overview	Section summary, executive brief	Stats bar, Card grid, Timeline, Annotation
AgentDetail	Per-agent deep dive	Card (identity), FlowDiagram (workflow), Table (guardrails), Badge (status)
Architecture	System diagrams, topology	FlowDiagram, Table (integration paths), ExpandableSection (layers)
Dashboard	Metrics, KPIs, health status	KpiCard grid, Badge indicators, Table (metrics)
TableView	Lists, matrices, registries	Table (sortable), ExpandableSection (row details)
Comparison	Before/After, options analysis	Side-by-side Card columns, Annotation
Timeline	Roadmap, Gantt, milestones	Timeline component, Card (phase details)
Document	Long-form content, specs	TabGroup (sections), CodeBlock, Annotation, Table

Hash Routing

useHash() Hook

const { page, setPage } = useHash('landing');
// page = current hash (e.g. 'agents')
// setPage('agents') → updates window.location.hash to #/agents

• URL pattern: #/page-id (e.g. #/agents, #/architecture)
• Default: 'landing' when hash is empty
• Browser back/forward supported via hashchange event
• No server needed — works in single HTML file
• Bookmarkable — sharing file.html#/agents opens the agents page directly

Router Pattern in App.tsx

function PageRouter({ page }: { page: string }) {
  const { lang } = useLang();
  switch (page) {
    case 'landing': return <Landing lang={lang} />;
    case 'overview': return <Overview lang={lang} />;
    case 'agents': return <AgentsPage lang={lang} />;
    // ... one case per page
    default: return <Landing lang={lang} />;
  }
}

Bundle Process

Default (portable — base64 logos)

bash scripts/bundle.sh

1. npm run build — Vite production build
2. Convert logo PNGs to base64 data URIs, inject into HTML/JS
3. npx html-inline — inline all JS/CSS into single HTML
4. Output: bundle.html (single self-contained file, <500KB target)

Workspace-local (relative paths)

bash scripts/bundle.sh --no-inline-images

Skips base64 conversion. Logos use relative paths. Smaller HTML, but only works from workspace directory.

Output Naming

Copy the bundle to the project output directory:

cp bundle.html ../../output/html/{Title}_v{version}_{YYYY-MM-DD}.html

Versioning & Archiving

• Filename: {Title}_v{version}_{YYYY-MM-DD}.html
• Save to: output/html/
• Before overwriting: move previous version to output/html/archive/
• Version, date, and client info embedded in Header and Footer

Factual Integrity

• NEVER fabricate metrics, KPIs, ROI, statistics, or research findings
• All content must come from source .md files — not invented by the agent
• Annotation educational content must be technically accurate
• If citing benchmarks, include hyperlinks to credible sources (Gartner, Forrester, DORA, Microsoft Learn, etc.)

Quality Checklist

• npm run dev starts without errors — landing page renders
• Sidebar navigation works — click each page, content renders, hash URL updates
• Browser back/forward works with hash routing
• Language selector switches ALL visible content (data + UI chrome)
• All 3 languages complete — no untranslated strings in PT-BR or ES
• Microsoft+GitHub logos visible in header (correct variant for background)
• Client logo in header center (if provided)
• Microsoft 4-color gradient bar under header
• Segoe UI font throughout
• Microsoft brand colors only — no arbitrary colors
• All cards/panels are interactive (hover effects, click to expand)
• Tables render with correct data, sortable where configured
• Code blocks have dark background (#1E1E1E) with copy button
• Annotations show correct colors (info=blue, success=green, warning=yellow, critical=red)
• Responsive: sidebar collapses to hamburger at <1024px
• bash scripts/bundle.sh produces single HTML under 500KB
• Bundle opens in Chrome, Edge, Safari, Firefox without errors
• No fabricated data in content — everything from source .md files
• Version, date, client name visible in header and footer
• Filename follows {Title}_v{version}_{date}.html pattern
• Previous version archived to output/html/archive/