From efdff310a2a91bbf6b65cbbdbacf4d334e3aa7ef Mon Sep 17 00:00:00 2001 From: Manfred Riem <15701806+mnriem@users.noreply.github.com> Date: Tue, 12 May 2026 17:39:38 -0500 Subject: [PATCH] docs: revamp landing page with four-pillar card layout (#2531) Rewrite docs/index.md from a philosophy essay into a landing page organized around four pillars: Spec-driven by default, Use any coding agent, Make it your own, and Integrate into your organization. - Add hero section with GitHub Spec Kit branding and CTA buttons - Add 2x2 pillar card grid with GitHub Primer color accents - Add community stats section (96K stars, 200+ contributors, etc.) - Add navigation cards and footer install CTA - Move SDD philosophy content to docs/concepts/sdd.md - Add custom DocFX template overlay with card CSS and dark mode - Set landing layout for index.md via fileMetadata - Update toc.yml and docfx.json for new concepts section --- docs/concepts/sdd.md | 46 ++++++ docs/docfx.json | 9 +- docs/index.md | 169 ++++++++++++++++------ docs/template/public/main.css | 264 ++++++++++++++++++++++++++++++++++ docs/toc.yml | 6 + 5 files changed, 451 insertions(+), 43 deletions(-) create mode 100644 docs/concepts/sdd.md create mode 100644 docs/template/public/main.css diff --git a/docs/concepts/sdd.md b/docs/concepts/sdd.md new file mode 100644 index 000000000..7f59feb51 --- /dev/null +++ b/docs/concepts/sdd.md @@ -0,0 +1,46 @@ +# What is Spec-Driven Development? + +Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them. + +## Core Philosophy + +Spec-Driven Development is a structured process that emphasizes: + +- **Intent-driven development** where specifications define the "*what*" before the "*how*" +- **Rich specification creation** using guardrails and organizational principles +- **Multi-step refinement** rather than one-shot code generation from prompts +- **Heavy reliance** on advanced AI model capabilities for specification interpretation + +## Development Phases + +| Phase | Focus | Key Activities | +|-------|-------|----------------| +| **0-to-1 Development** ("Greenfield") | Generate from scratch | | +| **Creative Exploration** | Parallel implementations | | +| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | + +## Experimental Goals + +Our research and experimentation focus on: + +### Technology Independence + +- Create applications using diverse technology stacks +- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks + +### Enterprise Constraints + +- Demonstrate mission-critical application development +- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) +- Support enterprise design systems and compliance requirements + +### User-Centric Development + +- Build applications for different user cohorts and preferences +- Support various development approaches (from vibe-coding to AI-native development) + +### Creative & Iterative Processes + +- Validate the concept of parallel implementation exploration +- Provide robust iterative feature development workflows +- Extend processes to handle upgrades and modernization tasks diff --git a/docs/docfx.json b/docs/docfx.json index c94476d82..62869e1d8 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -6,6 +6,7 @@ "*.md", "toc.yml", "community/*.md", + "concepts/*.md", "reference/*.md", "install/*.md" ] @@ -50,7 +51,8 @@ "fileMetadataFiles": [], "template": [ "default", - "modern" + "modern", + "template" ], "postProcessors": [], "markdownEngineName": "markdig", @@ -68,6 +70,11 @@ "repo": "https://github.com/github/spec-kit", "branch": "main" } + }, + "fileMetadata": { + "_layout": { + "index.md": "landing" + } } } } diff --git a/docs/index.md b/docs/index.md index a56fcc176..dba3b2c55 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,67 +1,152 @@ -# Spec Kit +
-*Build high-quality software faster.* +# GitHub Spec Kit -**An effort to allow organizations to focus on product scenarios rather than writing undifferentiated code with the help of Spec-Driven Development.** +**Define what to build before building it — with any AI coding agent.** -## What is Spec-Driven Development? +Spec Kit is a toolkit for [Spec-Driven Development](concepts/sdd.md) (SDD), a methodology that puts specifications at the center of AI-assisted software development. Instead of jumping straight to code, you describe *what* to build, refine it through structured phases, and let your AI coding agent implement it. -Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them. +Install Spec Kit  +Quick Start -## Getting Started +
-- [Installation Guide](installation.md) -- [Quick Start Guide](quickstart.md) -- [Upgrade Guide](upgrade.md) -- [Local Development](local-development.md) +--- -## Core Philosophy +
-Spec-Driven Development is a structured process that emphasizes: +
-- **Intent-driven development** where specifications define the "*what*" before the "*how*" -- **Rich specification creation** using guardrails and organizational principles -- **Multi-step refinement** rather than one-shot code generation from prompts -- **Heavy reliance** on advanced AI model capabilities for specification interpretation +### Spec-driven by default -## Development Phases +The core SDD process ships ready to use: **Spec → Plan → Tasks → Implement**. -| Phase | Focus | Key Activities | -|-------|-------|----------------| -| **0-to-1 Development** ("Greenfield") | Generate from scratch | | -| **Creative Exploration** | Parallel implementations | | -| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | | +Define what to build before building it. Rich templates, quality checklists, and cross-artifact analysis come out of the box. Each phase produces a Markdown artifact that feeds the next — giving your AI coding agent structured context instead of ad-hoc prompts. -## Experimental Goals +Walk through the workflow → -Our research and experimentation focus on: +
-### Technology Independence +
-- Create applications using diverse technology stacks -- Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks +### Use any coding agent -### Enterprise Constraints +30 integrations — Copilot, Gemini, Codex, Windsurf, Claude, Forge, Kiro, and more. Switch freely between agents with a single command. No lock-in. -- Demonstrate mission-critical application development -- Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) -- Support enterprise design systems and compliance requirements +Run `specify init` with your agent of choice and Spec Kit sets up the right command files, context rules, and directory structures automatically. If your agent isn't listed, the `generic` integration is an escape hatch for any tool. -### User-Centric Development +See all integrations → -- Build applications for different user cohorts and preferences -- Support various development approaches (from vibe-coding to AI-native development) +
-### Creative & Iterative Processes +
-- Validate the concept of parallel implementation exploration -- Provide robust iterative feature development workflows -- Extend processes to handle upgrades and modernization tasks +### Make it your own -## Contributing +91 community extensions (50+ authors), 18 presets, and growing — including entirely different SDD processes: -Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md) for information on how to contribute to this project. +- **AIDE** — 7-step AI-driven engineering lifecycle +- **Canon** — baseline-driven workflows (spec-first, code-first, spec-drift) +- **Product Forge** — product-management-oriented SDD +- **FX→.NET** — end-to-end .NET Framework migration across 7 phases +- **MAQA** — multi-agent orchestration with quality assurance gates -## Support +Tune the core process with presets, extend it with extensions, orchestrate it with workflows, or replace it entirely. Build and publish your own. -For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub. +Browse community presets → + +
+ +
+ +### Integrate into your organization + +Works offline, behind firewalls, and on **Windows, macOS, and Linux**. Host your own extension and preset catalogs so your organization controls what gets installed. + +Community extensions like CI Guard and Architecture Guard add compliance gates and governance that fit the way your team already works. + +Installation guide →   +Extensions reference → + +
+ +
+ +--- + +
+ +## Built by the community + +**200+ contributors** power the Spec Kit ecosystem — from core integrations to entirely new development processes. Anyone can create and publish an extension, preset, or workflow. + +
+
+ 96K+ + GitHub stars +
+
+ 200+ + Contributors +
+
+ 30 + Integrations +
+
+ 91 + Extensions +
+
+ 18 + Presets +
+
+ 4 + Friends projects +
+
+ +Presets · Walkthroughs · Friends + +
+ +--- + +## Explore the docs + +
+ + Getting Started + Install, configure, and run your first SDD workflow + + + Reference + Core commands, integrations, extensions, presets, and workflows + + + Community + Presets, walkthroughs, and friend projects + + + Development + Contribute to Spec Kit + + + What is SDD? + The philosophy behind Spec-Driven Development + +
+ +--- + +
+ +```bash +uvx --from git+https://github.com/github/spec-kit.git +specify init my-project --integration copilot +``` + +Ready to start? Follow the [Quick Start Guide](quickstart.md). + +
diff --git a/docs/template/public/main.css b/docs/template/public/main.css new file mode 100644 index 000000000..52ce45606 --- /dev/null +++ b/docs/template/public/main.css @@ -0,0 +1,264 @@ +/* Spec Kit landing page — GitHub Primer colors */ + +:root { + /* GitHub Primer palette */ + --gh-blue: #0969da; + --gh-green: #1a7f37; + --gh-purple: #8250df; + --gh-coral: #cf222e; + --gh-orange: #bf8700; + --gh-blue-subtle: #ddf4ff; + --gh-green-subtle: #dafbe1; + --gh-purple-subtle: #fbefff; + --gh-coral-subtle: #ffebe9; +} + +[data-bs-theme="dark"] { + --gh-blue: #58a6ff; + --gh-green: #3fb950; + --gh-purple: #bc8cff; + --gh-coral: #f85149; + --gh-orange: #d29922; + --gh-blue-subtle: #0d1d30; + --gh-green-subtle: #0d1d14; + --gh-purple-subtle: #1c0d2e; + --gh-coral-subtle: #2d0f0d; +} + +/* Override Bootstrap primary with GitHub blue */ +body[data-layout="landing"] { + --bs-primary: var(--gh-blue); + --bs-primary-rgb: 9, 105, 218; + --bs-link-color: var(--gh-blue); + --bs-link-hover-color: var(--gh-blue); +} + +[data-bs-theme="dark"] body[data-layout="landing"], +body[data-layout="landing"][data-bs-theme="dark"] { + --bs-primary-rgb: 88, 166, 255; +} + +/* Hero section */ +.landing-hero { + text-align: center; + padding: 3rem 0 1.5rem; +} + +.landing-hero h1 { + font-size: 2.6rem; + font-weight: 800; + margin-bottom: 0.5rem; + background: linear-gradient(135deg, var(--gh-blue), var(--gh-purple)); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +.landing-hero p { + font-size: 1.15rem; + max-width: 640px; + margin: 0 auto 1.5rem; + opacity: 0.85; +} + +.landing-hero .btn-primary { + background-color: var(--gh-blue); + border-color: var(--gh-blue); + color: #fff; +} + +.landing-hero .btn-primary:hover { + background-color: #0860ca; + border-color: #0860ca; +} + +.landing-hero .btn-outline-primary { + color: var(--gh-blue); + border-color: var(--gh-blue); +} + +.landing-hero .btn-outline-primary:hover { + background-color: var(--gh-blue); + border-color: var(--gh-blue); + color: #fff; +} + +/* Pillar cards grid */ +.pillar-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 1.5rem; + margin: 2rem 0; +} + +@media (max-width: 768px) { + .pillar-grid { + grid-template-columns: 1fr; + } +} + +.pillar-card { + border: 1px solid var(--bs-border-color); + border-radius: 0.5rem; + padding: 1.5rem; + background: var(--bs-body-bg); + transition: box-shadow 0.2s ease-in-out, border-color 0.2s ease-in-out; + border-top: 3px solid transparent; +} + +/* Each pillar gets a distinct GitHub color accent */ +.pillar-card:nth-child(1) { border-top-color: var(--gh-green); } +.pillar-card:nth-child(2) { border-top-color: var(--gh-blue); } +.pillar-card:nth-child(3) { border-top-color: var(--gh-purple); } +.pillar-card:nth-child(4) { border-top-color: var(--gh-coral); } + +.pillar-card:nth-child(1):hover { box-shadow: 0 4px 16px rgba(26, 127, 55, 0.12); } +.pillar-card:nth-child(2):hover { box-shadow: 0 4px 16px rgba(9, 105, 218, 0.12); } +.pillar-card:nth-child(3):hover { box-shadow: 0 4px 16px rgba(130, 80, 223, 0.12); } +.pillar-card:nth-child(4):hover { box-shadow: 0 4px 16px rgba(207, 34, 46, 0.12); } + +[data-bs-theme="dark"] .pillar-card:nth-child(1):hover { box-shadow: 0 4px 16px rgba(63, 185, 80, 0.15); } +[data-bs-theme="dark"] .pillar-card:nth-child(2):hover { box-shadow: 0 4px 16px rgba(88, 166, 255, 0.15); } +[data-bs-theme="dark"] .pillar-card:nth-child(3):hover { box-shadow: 0 4px 16px rgba(188, 140, 255, 0.15); } +[data-bs-theme="dark"] .pillar-card:nth-child(4):hover { box-shadow: 0 4px 16px rgba(248, 81, 73, 0.15); } + +.pillar-card h3 { + font-size: 1.2rem; + font-weight: 600; + margin-bottom: 0.75rem; +} + +/* Pillar headings pick up their card's accent color */ +.pillar-card:nth-child(1) h3 { color: var(--gh-green); } +.pillar-card:nth-child(2) h3 { color: var(--gh-blue); } +.pillar-card:nth-child(3) h3 { color: var(--gh-purple); } +.pillar-card:nth-child(4) h3 { color: var(--gh-coral); } + +.pillar-card .pillar-stat { + font-weight: 600; + color: var(--gh-blue); +} + +.pillar-card:nth-child(3) .pillar-stat { + color: var(--gh-purple); +} + +.pillar-card p:last-child { + margin-bottom: 0; +} + +.pillar-card ul { + padding-left: 1.2rem; + margin-bottom: 0.5rem; +} + +.pillar-card .pillar-link { + display: inline-block; + margin-top: 0.5rem; + font-size: 0.9rem; + font-weight: 500; +} + +.pillar-card:nth-child(1) .pillar-link { color: var(--gh-blue); } +.pillar-card:nth-child(2) .pillar-link { color: var(--gh-green); } +.pillar-card:nth-child(3) .pillar-link { color: var(--gh-purple); } +.pillar-card:nth-child(4) .pillar-link { color: var(--gh-coral); } + +/* Community stats section */ +.community-section { + text-align: center; + padding: 2rem 0; +} + +.stats-grid { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 1rem; + margin: 1.5rem auto; + max-width: 700px; +} + +@media (max-width: 576px) { + .stats-grid { + grid-template-columns: repeat(2, 1fr); + } +} + +.stat-item { + padding: 1rem; +} + +.stat-item .stat-number { + display: block; + font-size: 1.8rem; + font-weight: 700; + color: var(--gh-blue); + line-height: 1.2; +} + +.stat-item .stat-label { + display: block; + font-size: 0.85rem; + opacity: 0.75; + margin-top: 0.25rem; +} + +/* Nav cards */ +.nav-cards { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 1rem; + margin: 1.5rem 0; +} + +@media (max-width: 576px) { + .nav-cards { + grid-template-columns: 1fr; + } +} + +.nav-card { + border: 1px solid var(--bs-border-color); + border-radius: 0.5rem; + padding: 1rem 1.25rem; + text-decoration: none; + color: inherit; + transition: box-shadow 0.2s ease-in-out, border-color 0.2s ease-in-out; + display: block; + border-left: 3px solid var(--gh-blue); +} + +.nav-card:hover { + border-color: var(--gh-blue); + border-left-color: var(--gh-blue); + box-shadow: 0 2px 8px rgba(9, 105, 218, 0.1); + text-decoration: none; + color: inherit; +} + +[data-bs-theme="dark"] .nav-card:hover { + box-shadow: 0 2px 8px rgba(88, 166, 255, 0.12); +} + +.nav-card strong { + display: block; + margin-bottom: 0.25rem; + color: var(--gh-blue); +} + +.nav-card span { + font-size: 0.9rem; + opacity: 0.75; +} + +/* Footer CTA */ +.footer-cta { + text-align: center; + padding: 2rem 0 1rem; +} + +.footer-cta code { + font-size: 1.05rem; + padding: 0.5rem 1rem; + border-radius: 0.375rem; +} diff --git a/docs/toc.yml b/docs/toc.yml index 4101ae742..b163f9a0f 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -30,6 +30,12 @@ - name: Workflows href: reference/workflows.md +# Concepts +- name: Concepts + items: + - name: What is SDD? + href: concepts/sdd.md + # Development workflows - name: Development items: