diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index fef0a5e7..348edcf7 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -13,6 +13,65 @@ export default defineConfig({ }, description: "Enforce Architecture Decision Records as executable rules — for both humans and AI agents.", + customCss: ["./src/styles/custom.css"], + expressiveCode: { + // Disable Starlight's automatic UI color overrides so our + // hand-picked colors from archgate.dev take full effect. + useStarlightUiThemeColors: false, + styleOverrides: { + // ── Frame chrome — matches archgate.dev marketing site ─── + borderRadius: "0.75rem", + borderColor: "#333", + borderWidth: "1px", + + // ── Code area ─────────────────────────────────────────── + codeBackground: "#0f0f0f", + codeFontFamily: + '"SF Mono", "Cascadia Code", "Fira Code", Consolas, monospace', + codeFontSize: "0.85rem", + codeLineHeight: "1.7", + codePaddingBlock: "1.25rem", + codePaddingInline: "1.35rem", + + // ── Scrollbar ─────────────────────────────────────────── + scrollbarThumbColor: "#333", + scrollbarThumbHoverColor: "#555", + + // ── Frame-specific overrides ──────────────────────────── + frames: { + // Editor tabs (file names) + editorTabBarBackground: "#1a1a1a", + editorTabBarBorderColor: "transparent", + editorTabBarBorderBottomColor: "#333", + editorActiveTabBackground: "#1a1a1a", + editorActiveTabForeground: "#999", + editorActiveTabBorderColor: "transparent", + editorActiveTabIndicatorTopColor: "transparent", + editorActiveTabIndicatorBottomColor: "transparent", + editorBackground: "#0f0f0f", + + // Terminal title bar + terminalTitlebarBackground: "#1a1a1a", + terminalTitlebarForeground: "#555", + terminalTitlebarBorderBottomColor: "#333", + terminalTitlebarDotsForeground: "#555", + terminalTitlebarDotsOpacity: "0.8", + terminalBackground: "#0f0f0f", + + // Buttons (copy, etc.) + inlineButtonBackground: "#333", + inlineButtonForeground: "#999", + inlineButtonBorder: "#555", + + // No shadow — flat design like the website + frameBoxShadowCssValue: "none", + + // Tooltip + tooltipSuccessBackground: "#4ade80", + tooltipSuccessForeground: "#0f0f0f", + }, + }, + }, social: [ { icon: "github", diff --git a/docs/src/components/CodeShowcase.astro b/docs/src/components/CodeShowcase.astro new file mode 100644 index 00000000..7959966a --- /dev/null +++ b/docs/src/components/CodeShowcase.astro @@ -0,0 +1,298 @@ +--- +/** + * "ADRs that enforce themselves" — visual showcase ported from archgate.dev. + * Shows the ADR → Rules → Terminal output flow in three panels. + * + * Props: + * heading – section heading (translated per locale) + * subtext – description below the heading + */ +interface Props { + heading: string; + subtext: string; +} + +const { heading, subtext } = Astro.props; + +const adrCode = `--- +id: ARCH-003 +title: API Route Conventions +domain: backend +rules: true +files: + - "src/api/**/*.ts" +--- + +## Decision + +All API route handlers must use the +createRoute() factory function. +Direct export default is prohibited. + +## Do's and Don'ts + +DO: Use createRoute({ handler }) +DON'T: Use export default function`; + +const rulesCode = `import { defineRules } from "archgate/rules"; + +export default defineRules((ctx) => [ + { + name: "require-createRoute", + severity: "error", + async run() { + const files = await ctx.glob("src/api/**/*.ts"); + + for (const file of files) { + const hits = await ctx.grep( + file, /export\\s+default\\s+function/ + ); + for (const hit of hits) { + ctx.report({ + file, line: hit.line, + message: "Use createRoute() factory", + }); + } + } + }, + }, +]);`; +--- + +
+
+

{heading}

+

{subtext}

+
+ + +
+ +
+
+ + ARCH-003-api-routes.md +
+
+
+
+
+ + +
+
+ + ARCH-003-api-routes.rules.ts +
+
+
+
+
+
+ + +
+
+ + Terminal +
+
+
+ $ archgate check +
+
+ ARCH-003 API Route Conventions +
+
+ error + require-createRoute: Use createRoute() factory +
+
+ src/api/users/list.ts:14 +
+
+ 1 violation + found across 1 ADR +
+
+
+
+ + diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 251db7a1..4936b9b7 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -16,6 +16,7 @@ hero: --- import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; +import CodeShowcase from "../../components/CodeShowcase.astro"; ## How it works @@ -25,16 +26,10 @@ Archgate has two layers that work together: 2. **ADRs as rules** — Companion `.rules.ts` files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers. -``` -.archgate/ - adrs/ - ARCH-001-command-structure.md # The decision (human + AI readable) - ARCH-001-command-structure.rules.ts # The checks (machine executable) - ARCH-002-error-handling.md - ARCH-002-error-handling.rules.ts - lint/ - archgate.config.ts # Archgate configuration -``` + When you run `archgate check`, the CLI loads every ADR that has `rules: true` in its frontmatter, executes the companion rules file, and reports any violations. Exit code 0 means your code complies. Exit code 1 means it does not. diff --git a/docs/src/content/docs/pt-br/index.mdx b/docs/src/content/docs/pt-br/index.mdx index 349d8a06..f4f4c01d 100644 --- a/docs/src/content/docs/pt-br/index.mdx +++ b/docs/src/content/docs/pt-br/index.mdx @@ -16,6 +16,7 @@ hero: --- import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; +import CodeShowcase from "../../../components/CodeShowcase.astro"; ## Como funciona @@ -25,16 +26,10 @@ O Archgate possui duas camadas que trabalham juntas: 2. **ADRs como regras** — Arquivos complementares `.rules.ts` com verificações automatizadas escritas em TypeScript. Eles são executados contra sua base de código e reportam violações com caminhos de arquivos e números de linha. -``` -.archgate/ - adrs/ - ARCH-001-command-structure.md # The decision (human + AI readable) - ARCH-001-command-structure.rules.ts # The checks (machine executable) - ARCH-002-error-handling.md - ARCH-002-error-handling.rules.ts - lint/ - archgate.config.ts # Archgate configuration -``` + Quando você executa `archgate check`, a CLI carrega cada ADR que possui `rules: true` em seu frontmatter, executa o arquivo de regras complementar e reporta quaisquer violações. Código de saída 0 significa que seu código está em conformidade. Código de saída 1 significa que não está. diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css new file mode 100644 index 00000000..e1dae6d6 --- /dev/null +++ b/docs/src/styles/custom.css @@ -0,0 +1,46 @@ +/* + * Custom Starlight theme — matches the archgate.dev marketing site aesthetic. + * Terminal/editor window chrome: dark title bar with macOS dots, #0f0f0f code bg. + */ + +/* ── Starlight color overrides (dark mode) ─────────────────────────── */ +:root { + --sl-color-accent-low: #1e1b4b; + --sl-color-accent: #6366f1; + --sl-color-accent-high: #c7d2fe; +} + +/* ── Expressive Code frame refinements ─────────────────────────────── */ + +/* + * The title bar dots are SVG background-images generated by Expressive Code. + * We can't style them directly, but the `terminalTitlebarDotsForeground` + * and opacity styleOverrides in astro.config.mjs handle their color. + * + * Below we fine-tune spacing and visual weight to match the website. + */ + +/* Tighten the tab bar / title bar feel */ +.expressive-code .frame:not(.has-title):not(.is-terminal) .header { + display: none; +} + +/* Softer selection color matching the website */ +.expressive-code pre::selection, +.expressive-code pre *::selection, +.expressive-code code::selection, +.expressive-code code *::selection { + background-color: color-mix(in srgb, #6366f1 40%, transparent); +} + +/* Scrollbar theming for code blocks */ +.expressive-code pre::-webkit-scrollbar { + height: 6px; +} +.expressive-code pre::-webkit-scrollbar-thumb { + background: #333; + border-radius: 3px; +} +.expressive-code pre::-webkit-scrollbar-thumb:hover { + background: #555; +}