Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: revamp landing page with four-pillar card layout (#2531)

Manfred Riemefdff310a2a9
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 | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
+| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
+| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
+
+## 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
+<div class="landing-hero">
-*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.
+<a href="installation.md" class="btn btn-primary btn-lg">Install Spec Kit</a>&nbsp;
+<a href="quickstart.md" class="btn btn-outline-primary btn-lg">Quick Start</a>
-## Getting Started
+</div>
-- [Installation Guide](installation.md)
-- [Quick Start Guide](quickstart.md)
-- [Upgrade Guide](upgrade.md)
-- [Local Development](local-development.md)
+---
-## Core Philosophy
+<div class="pillar-grid">
-Spec-Driven Development is a structured process that emphasizes:
+<div class="pillar-card">
-- **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 | <ul><li>Start with high-level requirements</li><li>Generate specifications</li><li>Plan implementation steps</li><li>Build production-ready applications</li></ul> |
-| **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
-| **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |
+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
+<a href="quickstart.md" class="pillar-link">Walk through the workflow β†’</a>
-Our research and experimentation focus on:
+</div>
-### Technology Independence
+<div class="pillar-card">
-- 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
+<span class="pillar-stat">30 integrations</span> β€” 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
+<a href="reference/integrations.md" class="pillar-link">See all integrations β†’</a>
-- Build applications for different user cohorts and preferences
-- Support various development approaches (from vibe-coding to AI-native development)
+</div>
-### Creative & Iterative Processes
+<div class="pillar-card">
-- 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
+<span class="pillar-stat">91 community extensions</span> (50+ authors), <span class="pillar-stat">18 presets</span>, 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.
+<a href="community/presets.md" class="pillar-link">Browse community presets β†’</a>
+
+</div>
+
+<div class="pillar-card">
+
+### 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.
+
+<a href="installation.md" class="pillar-link">Installation guide β†’</a>&nbsp;&nbsp;
+<a href="reference/extensions.md" class="pillar-link">Extensions reference β†’</a>
+
+</div>
+
+</div>
+
+---
+
+<div class="community-section">
+
+## 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.
+
+<div class="stats-grid">
+ <div class="stat-item">
+ <span class="stat-number">96K+</span>
+ <span class="stat-label">GitHub stars</span>
+ </div>
+ <div class="stat-item">
+ <span class="stat-number">200+</span>
+ <span class="stat-label">Contributors</span>
+ </div>
+ <div class="stat-item">
+ <span class="stat-number">30</span>
+ <span class="stat-label">Integrations</span>
+ </div>
+ <div class="stat-item">
+ <span class="stat-number">91</span>
+ <span class="stat-label">Extensions</span>
+ </div>
+ <div class="stat-item">
+ <span class="stat-number">18</span>
+ <span class="stat-label">Presets</span>
+ </div>
+ <div class="stat-item">
+ <span class="stat-number">4</span>
+ <span class="stat-label">Friends projects</span>
+ </div>
+</div>
+
+<a href="community/presets.md">Presets</a> Β· <a href="community/walkthroughs.md">Walkthroughs</a> Β· <a href="community/friends.md">Friends</a>
+
+</div>
+
+---
+
+## Explore the docs
+
+<div class="nav-cards">
+ <a href="quickstart.md" class="nav-card">
+ <strong>Getting Started</strong>
+ <span>Install, configure, and run your first SDD workflow</span>
+ </a>
+ <a href="reference/overview.md" class="nav-card">
+ <strong>Reference</strong>
+ <span>Core commands, integrations, extensions, presets, and workflows</span>
+ </a>
+ <a href="community/presets.md" class="nav-card">
+ <strong>Community</strong>
+ <span>Presets, walkthroughs, and friend projects</span>
+ </a>
+ <a href="local-development.md" class="nav-card">
+ <strong>Development</strong>
+ <span>Contribute to Spec Kit</span>
+ </a>
+ <a href="concepts/sdd.md" class="nav-card">
+ <strong>What is SDD?</strong>
+ <span>The philosophy behind Spec-Driven Development</span>
+ </a>
+</div>
+
+---
+
+<div class="footer-cta">
+
+```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).
+
+</div>
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: