From a21bb982cb99ebd539663b15d20c878e8d270631 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sun, 1 Mar 2026 17:44:28 +0100 Subject: [PATCH 1/4] feat(docs): port terminal/editor window chrome from marketing site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Style code blocks in the CLI docs to match the archgate.dev marketing site aesthetic — dark title bars (#1a1a1a), macOS-style dots, #0f0f0f code backgrounds, flat design with no shadows, and matching scrollbar and selection colors. Co-Authored-By: Claude Opus 4.6 --- docs/astro.config.mjs | 59 ++++++++++++++++++++++++++++++++++++++ docs/src/styles/custom.css | 46 +++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 docs/src/styles/custom.css 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/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; +} From 8e9bd38facc4207c4c309e1080293d1e4ce8047c Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sun, 1 Mar 2026 17:50:51 +0100 Subject: [PATCH 2/4] feat(docs): add "ADRs that enforce themselves" showcase section Port the three-panel visual showcase from archgate.dev into the docs landing page: ADR file + Rules file side-by-side, with terminal output below showing `archgate check` results. Replaces the plain directory tree with an interactive visual that demonstrates the full ADR-to-check flow. Includes pt-br translation. Co-Authored-By: Claude Opus 4.6 --- docs/src/components/CodeShowcase.astro | 247 +++++++++++++++++++++++++ docs/src/content/docs/index.mdx | 15 +- docs/src/content/docs/pt-br/index.mdx | 15 +- 3 files changed, 257 insertions(+), 20 deletions(-) create mode 100644 docs/src/components/CodeShowcase.astro diff --git a/docs/src/components/CodeShowcase.astro b/docs/src/components/CodeShowcase.astro new file mode 100644 index 00000000..203cde38 --- /dev/null +++ b/docs/src/components/CodeShowcase.astro @@ -0,0 +1,247 @@ +--- +/** + * "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á. From 02d733e863c6217c8c991437a9c058f586fda8d0 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sun, 1 Mar 2026 18:19:45 +0100 Subject: [PATCH 3/4] fix(docs): use :global() for set:html syntax highlight spans Astro scopes From 737e10b62f742802506f94235dab4c72f683a902 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sun, 1 Mar 2026 18:34:50 +0100 Subject: [PATCH 4/4] fix(docs): add light mode support and fix panel alignment - Use CSS custom properties with [data-theme] selectors for light/dark - Add not-content class to opt out of Starlight's prose styles that broke panel alignment - Set panel background so dark bg fills the entire window frame - Light palette: #f8f9fa bg, #eef0f2 chrome, darker syntax colors Co-Authored-By: Claude Opus 4.6 --- docs/src/components/CodeShowcase.astro | 85 +++++++++++++++++++------- 1 file changed, 63 insertions(+), 22 deletions(-) diff --git a/docs/src/components/CodeShowcase.astro b/docs/src/components/CodeShowcase.astro index 1658762e..7959966a 100644 --- a/docs/src/components/CodeShowcase.astro +++ b/docs/src/components/CodeShowcase.astro @@ -59,7 +59,7 @@ const rulesCode = `import { defineRules } +

{heading}

{subtext}

@@ -125,10 +125,49 @@ const rulesCode = `import { defineRules }