diff --git a/.rulesync/README.md b/.rulesync/README.md index 6b93ffdc306..b041de75cb0 100644 --- a/.rulesync/README.md +++ b/.rulesync/README.md @@ -53,16 +53,27 @@ Quick-reference for all AI agent commands, skills, sub-agents, and rules availab | Command | šŸ”µ `/plan-implementation-review` | `/plan-implementation-review` | Review plan execution, identify delivery gaps | | Agent | šŸ”µ `nx-expert` | Auto | Nx monorepo configuration and build optimisation | +## Context and Memory + +| Type | Name | Invoke | What it does | +| ------- | -------------- | ----------- | -------------------------------------------------- | +| Command | šŸ”µ `/remember` | `/remember` | Save branch context or project learnings as memory | +| Command | šŸ”µ `/recall` | `/recall` | Load branch context and browse project memory | + +## Documentation Review + +| Type | Name | Invoke | What it does | +| ------- | ------------------------- | ---------------------- | ---------------------------------------------------------------- | +| Command | šŸŸ¢ `/docs-review` | `/docs-review` | Review docs pages for technical accuracy and example consistency | +| Command | šŸŸ¢ `/release-docs-review` | `/release-docs-review` | Review all documentation changes between releases | + ## Git and Branch Management -| Type | Name | Invoke | What it does | -| ------- | ----------------------------- | -------------------------- | ---------------------------------------------- | -| Command | šŸ”µ `/git-branch-save-context` | `/git-branch-save-context` | Save branch-specific context to `.context/` | -| Command | šŸ”µ `/git-branch-load-context` | `/git-branch-load-context` | Load branch-specific context from `.context/` | -| Command | šŸ”µ `/git-worktree-clean` | `/git-worktree-clean` | Hard-reset worktree to `origin/latest` | -| Command | šŸ”µ `/git-split` | `/git-split` | Split large files preserving git history | -| Command | šŸ”µ `/pr-split` | `/pr-split` | Split a branch into stacked PRs | -| Command | šŸ”µ `/context-remember` | `/context-remember` | Persist learnings from conversations as memory | +| Type | Name | Invoke | What it does | +| ------- | ------------------------ | --------------------- | ---------------------------------------- | +| Command | šŸ”µ `/git-worktree-clean` | `/git-worktree-clean` | Hard-reset worktree to `origin/latest` | +| Command | šŸ”µ `/git-split` | `/git-split` | Split large files preserving git history | +| Command | šŸ”µ `/pr-split` | `/pr-split` | Split a branch into stacked PRs | --- diff --git a/.rulesync/commands/context-remember.md b/.rulesync/commands/context-remember.md deleted file mode 120000 index 3230ebac763..00000000000 --- a/.rulesync/commands/context-remember.md +++ /dev/null @@ -1 +0,0 @@ -../../external/ag-shared/prompts/commands/context/remember.md \ No newline at end of file diff --git a/.rulesync/commands/docs-e2e-tests.md b/.rulesync/commands/docs-e2e-tests.md index b02bacb84f2..c7f02b9c7b4 100644 --- a/.rulesync/commands/docs-e2e-tests.md +++ b/.rulesync/commands/docs-e2e-tests.md @@ -205,10 +205,9 @@ Group footer rows display `"Total {groupName}"` in the auto group column. Grand ```typescript // Group footer -await expect(agIdFor.autoGroupCell('rowGroupFooter_row-group-country-Netherlands')).toContainText( - 'Total Netherlands', - { useInnerText: true } -); +await expect(agIdFor.autoGroupCell('rowGroupFooter_row-group-country-Netherlands')).toContainText('Total Netherlands', { + useInnerText: true, +}); // Grand total footer await expect(agIdFor.autoGroupCell('rowGroupFooter_ROOT_NODE_ID').first()).toContainText('Total', { diff --git a/.rulesync/commands/docs-review.md b/.rulesync/commands/docs-review.md new file mode 100644 index 00000000000..f9313398a04 --- /dev/null +++ b/.rulesync/commands/docs-review.md @@ -0,0 +1,125 @@ +--- +targets: ['*'] +description: 'Review documentation pages for technical accuracy and example consistency' +--- + +# Documentation Review - AG Grid + +You are a technical documentation reviewer for AG Grid. + +## Product Configuration + +### Input Requirements + +> Required ā€” referenced by exact name in the core methodology. + +User provides: + +- Documentation page path: `documentation/ag-grid-docs/src/content/docs/${pageName}/index.mdoc` +- Live dev URL: `https://localhost:4610/javascript-data-grid/${pageName}/` + +### Orchestration Indicator + +- Orchestrator script: none + +### File Resolution Rules + +> Required ā€” referenced by exact name in the core methodology. + +Map documentation references to TypeScript definition files: + +| If docs mention | Then check file | +| ----------------------------------------- | --------------------------------------------------------------------------------------------- | +| GridOptions / grid option property | `packages/ag-grid-community/src/entities/gridOptions.ts` | +| ColDef / column definition property | `packages/ag-grid-community/src/entities/colDef.ts` | +| Interface name like `I*` or specific type | Search `packages/ag-grid-community/src/**/*.ts` and `packages/ag-grid-enterprise/src/**/*.ts` | +| API function / grid API method | `packages/ag-grid-community/src/api/gridApi.ts` | + +### Implementation Resolution Rules + +> Required ā€” referenced by exact name in the core methodology. + +Map features to source implementation files: + +| Feature Category | Implementation Path Pattern | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Row models (CSRM, SSRM, infinite, viewport) | `packages/ag-grid-community/src/clientSideRowModel/**/*.ts`, `packages/ag-grid-community/src/infiniteRowModel/**/*.ts`, `packages/ag-grid-enterprise/src/serverSideRowModel/**/*.ts`, `packages/ag-grid-enterprise/src/viewportRowModel/**/*.ts` | +| Column features (sizing, moving, pinning) | `packages/ag-grid-community/src/columns/**/*.ts`, `packages/ag-grid-community/src/columnMove/**/*.ts`, `packages/ag-grid-community/src/columnResize/**/*.ts`, `packages/ag-grid-community/src/columnAutosize/**/*.ts`, `packages/ag-grid-community/src/pinnedColumns/**/*.ts` | +| Cell editing | `packages/ag-grid-community/src/edit/**/*.ts` | +| Filtering | `packages/ag-grid-community/src/filter/**/*.ts`, `packages/ag-grid-enterprise/src/advancedFilter/**/*.ts` | +| Row grouping / pivoting | `packages/ag-grid-enterprise/src/rowGrouping/**/*.ts`, `packages/ag-grid-enterprise/src/pivot/**/*.ts` | +| Selection | `packages/ag-grid-community/src/selection/**/*.ts`, `packages/ag-grid-enterprise/src/rangeSelection/**/*.ts` | +| Export (CSV/Excel) | `packages/ag-grid-community/src/csvExport/**/*.ts`, `packages/ag-grid-enterprise/src/excelExport/**/*.ts` | +| Master detail | `packages/ag-grid-enterprise/src/masterDetail/**/*.ts` | +| Menu / context menu | `packages/ag-grid-enterprise/src/menu/**/*.ts` | +| Charts integration | `packages/ag-grid-enterprise/src/charts/**/*.ts` | +| Rich select / editors | `packages/ag-grid-enterprise/src/richSelect/**/*.ts` | +| Sorting | `packages/ag-grid-community/src/sort/**/*.ts` | +| Pagination | `packages/ag-grid-community/src/pagination/**/*.ts` | +| Tooltips | `packages/ag-grid-community/src/tooltip/**/*.ts` | +| Drag and drop / row drag | `packages/ag-grid-community/src/dragAndDrop/**/*.ts` | +| Keyboard navigation | `packages/ag-grid-community/src/navigation/**/*.ts` | +| Pinned rows | `packages/ag-grid-community/src/pinnedRowModel/**/*.ts` | +| Clipboard | `packages/ag-grid-enterprise/src/clipboard/**/*.ts` | +| Status bar | `packages/ag-grid-enterprise/src/statusBar/**/*.ts` | +| Side bar / tool panels | `packages/ag-grid-enterprise/src/sideBar/**/*.ts`, `packages/ag-grid-enterprise/src/columnToolPanel/**/*.ts`, `packages/ag-grid-enterprise/src/filterToolPanel/**/*.ts` | +| Set filter | `packages/ag-grid-enterprise/src/setFilter/**/*.ts` | +| Tree data | `packages/ag-grid-enterprise/src/treeData/**/*.ts` | +| Aggregation | `packages/ag-grid-enterprise/src/aggregation/**/*.ts` | +| Sparklines | `packages/ag-grid-enterprise/src/sparkline/**/*.ts` | + +### Example Path Pattern + +> Required ā€” referenced by exact name in the core methodology. + +`documentation/ag-grid-docs/src/content/docs/${pageName}/_examples/${exampleName}/` + +- Required: `main.ts` +- Optional: `data.ts`, `styles.css`, `provided/modules/*` + +### Example Direct URL Pattern + +> Optional ā€” referenced by exact name in the core methodology. + +`https://localhost:4610/examples/${pageName}/${exampleName}/vanilla` + +The `vanilla` framework variant is used as it loads slightly faster than `typescript`. + +### Exceptions File Path + +`documentation/ag-grid-docs/src/content/docs/${pageName}/technical-review-exceptions.md` + +### Output Paths + +> Required ā€” referenced by exact name in the core methodology. + +- Review plans: `reports/docs-review/plans/${pageName}.md` +- Reports: `documentation/ag-grid-docs/src/content/docs/${pageName}/reports/technical-review-report.md` +- Summary: `reports/docs-review/summary.md` + +### Default Value Verification Hierarchy + +> Required ā€” referenced by exact name in the core methodology. + +1. First: Check `packages/ag-grid-community/src/gridOptionsDefault.ts` for runtime defaults +2. Then: Check `packages/ag-grid-community/src/gridOptionsInitial.ts` for non-reactive properties (only read at grid initialisation) +3. Fallback: Check interface definition TypeScript comments in `entities/gridOptions.ts` or `entities/colDef.ts` +4. Verify: TypeScript JSDoc comments match actual runtime defaults + +### Product-Specific Conventions + +- Interface naming: `GridOptions`, `ColDef`, `ColGroupDef`, `RowNode`, `ICellRendererParams` etc. +- Column definitions use `ColDef` interface, not `ColumnDef` +- Grid API accessed via `api` property on the grid instance +- Enterprise features require `ag-grid-enterprise` package ā€” docs should note enterprise-only features +- Examples support React, Angular, Vue 3 and vanilla JS frameworks + +### Browser Testing Tips + +> Required ā€” referenced by exact name in the core methodology. + +`.rulesync/rules/docs-review-testing.md` + +## Review Methodology + +**Read and follow all instructions in `external/ag-shared/prompts/commands/docs/_docs-review-core.md` for the review process, applying the product configuration above.** diff --git a/.rulesync/commands/git-branch-load-context.md b/.rulesync/commands/git-branch-load-context.md deleted file mode 120000 index d4cb612548a..00000000000 --- a/.rulesync/commands/git-branch-load-context.md +++ /dev/null @@ -1 +0,0 @@ -../../external/ag-shared/prompts/commands/git/branch-load-context.md \ No newline at end of file diff --git a/.rulesync/commands/git-branch-save-context.md b/.rulesync/commands/git-branch-save-context.md deleted file mode 120000 index c81dadd0f9f..00000000000 --- a/.rulesync/commands/git-branch-save-context.md +++ /dev/null @@ -1 +0,0 @@ -../../external/ag-shared/prompts/commands/git/branch-save-context.md \ No newline at end of file diff --git a/.rulesync/commands/recall.md b/.rulesync/commands/recall.md new file mode 120000 index 00000000000..294bb6c1836 --- /dev/null +++ b/.rulesync/commands/recall.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/commands/recall.md \ No newline at end of file diff --git a/.rulesync/commands/release-docs-review.md b/.rulesync/commands/release-docs-review.md new file mode 100644 index 00000000000..d28f1fcbac6 --- /dev/null +++ b/.rulesync/commands/release-docs-review.md @@ -0,0 +1,65 @@ +--- +targets: ['*'] +description: 'Review all documentation changes between releases for accuracy and completeness' +--- + +# Release Documentation Review - AG Grid + +You are an expert documentation reviewer for AG Grid, specialising in +release documentation validation. + +## Product Configuration + +### Product + +> Required ā€” referenced by exact name in the core methodology. + +- Name: AG Grid +- Docs review command: `/docs-review` + +### Paths + +> Required ā€” referenced by exact name in the core methodology. + +- Docs root: `documentation/ag-grid-docs/src/content/docs` +- Types root: `packages/ag-grid-community/src` +- Docs file pattern: `documentation/ag-grid-docs/src/content/docs/**/*.mdoc` +- Examples pattern: `documentation/ag-grid-docs/src/content/docs/**/_examples/` +- Types file pattern: `packages/ag-grid-community/src/**/*.ts` + +### Release Branch Pattern + +> Required ā€” referenced by exact name in the core methodology. + +- Format: `origin/bX.Y.Z` +- Discovery command: `git branch -r | grep 'origin/b[0-9]' | sort -V | tail -5` + +### Priority Pages + +> Required ā€” referenced by exact name in the core methodology. + +**High priority** (getting started, key features, upgrade guides): +`getting-started, quick-start, deep-dive, upgrading-to-ag-grid-34, row-data, column-definitions, grid-options, grid-interface` + +**Medium priority** (core features): +`cell-editing, filtering, sorting, row-selection, cell-selection, row-grouping, server-side-model, master-detail, column-headers, themes, accessibility` + +### Output Paths + +> Required ā€” referenced by exact name in the core methodology. + +- Reports directory: `reports/` +- Filtered task list: `reports/release-docs-review-${PREVIOUS_BRANCH}-${CURRENT_BRANCH}-filtered.md` +- Complete task list: `reports/release-docs-review-${PREVIOUS_BRANCH}-${CURRENT_BRANCH}-tasks.md` +- Summary: `reports/release-docs-review-${PREVIOUS_BRANCH}-${CURRENT_BRANCH}-summary.md` + +### Verification Paths + +After each page review, confirm these files exist: + +- `reports/docs-review/plans/${pageName}.md` +- `documentation/ag-grid-docs/src/content/docs/${pageName}/reports/technical-review-report.md` + +## Review Methodology + +**Read and follow all instructions in `external/ag-shared/prompts/commands/docs/_release-docs-review-core.md` for the review process, applying the product configuration above.** diff --git a/.rulesync/commands/remember.md b/.rulesync/commands/remember.md new file mode 120000 index 00000000000..6ed9f690adb --- /dev/null +++ b/.rulesync/commands/remember.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/commands/remember.md \ No newline at end of file diff --git a/.rulesync/rules/ag-grid.md b/.rulesync/rules/ag-grid.md index 2d8eae71e4f..e2312504cfb 100644 --- a/.rulesync/rules/ag-grid.md +++ b/.rulesync/rules/ag-grid.md @@ -18,7 +18,7 @@ This file provides guidance to AI Agents when working with code in this reposito - **Build:** `yarn nx build ` - **Test:** `yarn nx test ` - **E2E:** `yarn nx e2e ag-grid-docs` -- **Dev server:** `yarn nx dev` +- **Dev server:** `yarn nx dev` (launches on https://localhost:4610/, check if it is already running before trying to run it) ### Content Locations @@ -99,6 +99,10 @@ Run rulesync commands via slash notation: - `/batch-lint-cleanup` - ESLint auto-fix tool - `/git-split` - Split large files preserving git history - `/git-bisect` - Find commits that introduced issues +- `/remember` - Save branch context or project learnings as memory +- `/recall` - Load branch context and browse project memory +- `/docs-review` - Review documentation pages for technical accuracy +- `/release-docs-review` - Review all documentation changes between releases ### Architecture diff --git a/.rulesync/rules/docs-review-testing.md b/.rulesync/rules/docs-review-testing.md new file mode 100644 index 00000000000..5e8953df2a6 --- /dev/null +++ b/.rulesync/rules/docs-review-testing.md @@ -0,0 +1,38 @@ +--- +targets: ['*'] +description: 'Browser testing tips for documentation review' +--- + +# Documentation Review - Browser Testing + +Tips for browser-testing AG Grid documentation pages via chrome automation. + +## Page Navigation + +- AG Grid example grids are rendered inside iframes. Scrolling while the cursor is over a grid example scrolls the grid's rows, not the page itself. +- To navigate down the page, scroll outside the grid area (e.g., over prose text or margins), or use keyboard navigation (`End`, `Home`, `Page Down`/`Page Up`). +- Use anchor links (`#section-name`) in the URL to jump directly to specific sections rather than scrolling through the entire page. + +## Example Testing + +- Each example has interactive controls (buttons, dropdowns) rendered above the grid iframe. Click them to verify the documented behaviour. +- After clicking an interactive control, take a screenshot to capture the result state. +- Check the browser console for errors after testing examples ā€” expected messages like AG Grid Enterprise license warnings can be ignored. + +## URL Pattern + +- Dev server docs pages require a framework prefix: `https://localhost:4610/javascript-data-grid/${pageName}/` +- The framework prefix can be changed to test other frameworks: `react-data-grid`, `angular-data-grid`, `vue-data-grid`. + +## Direct URL Testing (Sub-agent Mode) + +When the product configuration includes an **Example Direct URL Pattern**, example browser testing is delegated to a `docs-example-browser-tester` sub-agent that opens each example at its standalone URL. + +Direct URL characteristics: + +- Examples render full-viewport with no docs page chrome, no iframe wrapper. +- Interactive controls (buttons, dropdowns) from the example's `index.html` are directly accessible without scrolling past documentation content. +- Console messages come from the example only, not the surrounding docs page. +- Screenshots capture the complete example without docs page chrome. + +The main agent retains responsibility for page-level visual/interaction testing (Step 6) which requires the full docs page context (theme switchers, framework selectors, cross-references, keyboard navigation). diff --git a/.rulesync/rules/nx-conventions.md b/.rulesync/rules/nx-conventions.md new file mode 120000 index 00000000000..6b5a42e8400 --- /dev/null +++ b/.rulesync/rules/nx-conventions.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/guides/nx-conventions.md \ No newline at end of file diff --git a/.rulesync/rules/setup-prompts.md b/.rulesync/rules/setup-prompts.md new file mode 120000 index 00000000000..27bfa821d75 --- /dev/null +++ b/.rulesync/rules/setup-prompts.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/guides/setup-prompts.md \ No newline at end of file diff --git a/.rulesync/rules/website-astro-pages.md b/.rulesync/rules/website-astro-pages.md new file mode 120000 index 00000000000..bfeabc5b649 --- /dev/null +++ b/.rulesync/rules/website-astro-pages.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/guides/website-astro-pages.md \ No newline at end of file diff --git a/.rulesync/rules/website-browser-testing.md b/.rulesync/rules/website-browser-testing.md new file mode 120000 index 00000000000..1463b097e58 --- /dev/null +++ b/.rulesync/rules/website-browser-testing.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/guides/website-browser-testing.md \ No newline at end of file diff --git a/.rulesync/rules/website-css.md b/.rulesync/rules/website-css.md new file mode 120000 index 00000000000..be40f6320fd --- /dev/null +++ b/.rulesync/rules/website-css.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/guides/website-css.md \ No newline at end of file diff --git a/.rulesync/subagents/docs-example-browser-tester.md b/.rulesync/subagents/docs-example-browser-tester.md new file mode 120000 index 00000000000..12d6ed84a37 --- /dev/null +++ b/.rulesync/subagents/docs-example-browser-tester.md @@ -0,0 +1 @@ +../../external/ag-shared/prompts/agents/docs-example-browser-tester.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 5366ec3d5aa..dbe14e41808 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -92,6 +92,10 @@ Run rulesync commands via slash notation: - `/batch-lint-cleanup` - ESLint auto-fix tool - `/git-split` - Split large files preserving git history - `/git-bisect` - Find commits that introduced issues +- `/remember` - Save branch context or project learnings as memory +- `/recall` - Load branch context and browse project memory +- `/docs-review` - Review documentation pages for technical accuracy +- `/release-docs-review` - Review all documentation changes between releases ### Architecture diff --git a/documentation/ag-grid-docs/src/components/reference-documentation/utils/getPropertiesFromSource.ts b/documentation/ag-grid-docs/src/components/reference-documentation/utils/getPropertiesFromSource.ts index e2611677b69..b2c62d21cd5 100644 --- a/documentation/ag-grid-docs/src/components/reference-documentation/utils/getPropertiesFromSource.ts +++ b/documentation/ag-grid-docs/src/components/reference-documentation/utils/getPropertiesFromSource.ts @@ -51,6 +51,12 @@ export const getPropertiesFromSource = async ({ }); const codeConfigs = Object.fromEntries(codeConfigEntries); + // Validate that theming-api/properties.json keys match the theming-api.AUTO.json keys + // Only run when actually processing the theming-api source + if (sources.some((s) => s.includes('theming-api'))) { + validateThemingApiProperties(propertiesFromFiles, codeConfigs); + } + return { sources, propertiesFromFiles, @@ -58,3 +64,35 @@ export const getPropertiesFromSource = async ({ codeConfigs, }; }; + +function validateThemingApiProperties(properties: any[], codeConfigs: any) { + const codeSrc = 'theming-api.AUTO.json'; + const propsFile = properties.find((p) => p['_config_']?.codeSrc === codeSrc); + if (!propsFile) { + throw new Error(`No properties.json with codeSrc: "${codeSrc}"`); + } + const codeConfig = codeConfigs[codeSrc]; + if (!codeConfig) { + throw new Error(`Theme params codeSrc file not found: ${codeSrc}`); + } + const codeKeys = new Set(Object.keys(codeConfig)); + const propsKeys = Object.entries(propsFile) + .filter(([k]) => k !== '_config_') + .flatMap(([, section]) => Object.keys(section as object).filter((k) => k !== 'meta')); + const missing = propsKeys.filter((k) => !codeKeys.has(k)); + const extra = [...codeKeys].filter((k) => !propsKeys.includes(k)); + if (missing.length || extra.length) { + const msgs: string[] = []; + if (missing.length) { + msgs.push( + `These theme params are documented in theming-api/properties.json but not in the API (checking ${codeSrc}): ${missing.join(', ')}` + ); + } + if (extra.length) { + msgs.push( + `These theme params are present in the API (checking ${codeSrc}) but not documented in theming-api/properties.json: ${extra.join(', ')}` + ); + } + throw new Error(msgs.join('\n')); + } +} diff --git a/documentation/ag-grid-docs/src/components/theme-builder/model/ParamModel.ts b/documentation/ag-grid-docs/src/components/theme-builder/model/ParamModel.ts index f251461ab28..8f9419c157d 100644 --- a/documentation/ag-grid-docs/src/components/theme-builder/model/ParamModel.ts +++ b/documentation/ag-grid-docs/src/components/theme-builder/model/ParamModel.ts @@ -1,8 +1,9 @@ -import { type ParamType, getParamDocs, getParamType } from '@components/theme-builder/api'; +import { type ParamType, getParamType } from '@components/theme-builder/api'; import { useAtom, useAtomValue } from 'jotai'; import { themeQuartz } from 'ag-grid-community'; +import themingApi from '../../../../../../dist/documentation/reference/theming-api.AUTO.json'; import { getThemeDefaultParams } from '../components/component-utils'; import type { PersistentAtom } from './JSONStorage'; import { atomWithJSONStorage } from './JSONStorage'; @@ -79,3 +80,7 @@ export const allParamModels = memoize(() => { const allParams = Array.from(Object.keys(defaultModeParams)) as ThemeParam[]; return allParams.map(ParamModel.for).sort((a, b) => a.label.toLowerCase().localeCompare(b.label.toLowerCase())); }); + +export function getParamDocs(param: string): string | undefined { + return (themingApi as Record)[param]?.meta?.comment; +} diff --git a/documentation/ag-grid-docs/src/content/api-documentation/theming-api/properties.json b/documentation/ag-grid-docs/src/content/api-documentation/theming-api/properties.json new file mode 100644 index 00000000000..c65a2b58c08 --- /dev/null +++ b/documentation/ag-grid-docs/src/content/api-documentation/theming-api/properties.json @@ -0,0 +1,523 @@ +{ + "_config_": { + "codeSrc": "theming-api.AUTO.json", + "codeWordsMode": "cssVariable" + }, + "colorsAndDarkMode": { + "meta": { + "displayName": "Colours & Dark Mode", + "page": { + "name": "Theming: Colours & Dark Mode", + "url": "./theming-colors/" + } + }, + "accentColor": {}, + "backgroundColor": {}, + "borderColor": {}, + "browserColorScheme": {}, + "cellTextColor": {}, + "chromeBackgroundColor": {}, + "dataBackgroundColor": {}, + "foregroundColor": {}, + "invalidColor": {}, + "subtleTextColor": {}, + "textColor": {} + }, + "fonts": { + "meta": { + "displayName": "Fonts", + "page": { + "name": "Theming: Customising Fonts", + "url": "./theming-fonts/" + } + }, + "cellFontFamily": {}, + "cellTextColor": {}, + "dataFontSize": {}, + "fontFamily": {}, + "fontSize": {}, + "headerFontFamily": {}, + "headerFontSize": {}, + "headerFontWeight": {} + }, + "borders": { + "meta": { + "displayName": "Borders", + "page": { + "name": "Theming API: Customising Borders", + "url": "./theming-borders/" + } + }, + "borderRadius": {}, + "borderWidth": {}, + "borderColor": {}, + "columnBorder": {}, + "footerRowBorder": {}, + "headerColumnBorder": {}, + "headerRowBorder": {}, + "pinnedColumnBorder": {}, + "pinnedRowBorder": {}, + "rowBorder": {}, + "sidePanelBorder": {}, + "wrapperBorder": {}, + "wrapperBorderRadius": {} + }, + "spacingAndSizing": { + "meta": { + "displayName": "Spacing & Sizing", + "page": { + "name": "Theming: Compactness & Row Height", + "url": "./theming-compactness/" + } + }, + "cellHorizontalPadding": {}, + "cellHorizontalPaddingScale": {}, + "cellWidgetSpacing": {}, + "headerHeight": {}, + "headerVerticalPaddingScale": {}, + "iconSize": {}, + "listItemHeight": {}, + "paginationPanelHeight": {}, + "rowHeight": {}, + "rowVerticalPaddingScale": {}, + "spacing": {}, + "widgetContainerHorizontalPadding": {}, + "widgetContainerVerticalPadding": {}, + "widgetHorizontalSpacing": {}, + "widgetVerticalSpacing": {} + }, + "data": { + "meta": { + "displayName": "Data Rows & Columns", + "page": { + "name": "Row Styles", + "url": "./row-styles/" + } + }, + "cellFontFamily": {}, + "cellTextColor": {}, + "columnHoverColor": {}, + "dataBackgroundColor": {}, + "dataFontSize": {}, + "oddRowBackgroundColor": {}, + "pinnedRowBackgroundColor": {}, + "pinnedRowFontWeight": {}, + "pinnedRowTextColor": {}, + "pinnedSourceRowBackgroundColor": {}, + "pinnedSourceRowFontWeight": {}, + "pinnedSourceRowTextColor": {}, + "rowGroupIndentSize": {}, + "rowHoverColor": {}, + "rowLoadingSkeletonEffectColor": {}, + "valueChangeDeltaDownColor": {}, + "valueChangeDeltaUpColor": {}, + "valueChangeValueHighlightBackgroundColor": {} + }, + "selections": { + "meta": { + "displayName": "Selections", + "description": "Style [Cell Selection](./cell-selection/) and [Row Selection](./row-selection/), see also [Theming: Customising Selections](./theming-selections/)" + }, + "rangeHeaderHighlightColor": {}, + "rangeSelectionBackgroundColor": {}, + "rangeSelectionBorderColor": {}, + "rangeSelectionBorderStyle": {}, + "rangeSelectionChartBackgroundColor": {}, + "rangeSelectionChartCategoryBackgroundColor": {}, + "rangeSelectionHighlightColor": {}, + "rowNumbersSelectedColor": {}, + "selectedRowBackgroundColor": {} + }, + "headers": { + "meta": { + "displayName": "Headers", + "description": "Style [Column Headers](./column-headers/), see also [Theming: Customising Headers](./theming-headers/)" + }, + "headerBackgroundColor": {}, + "headerCellBackgroundTransitionDuration": {}, + "headerCellHoverBackgroundColor": {}, + "headerCellMovingBackgroundColor": {}, + "headerColumnBorderHeight": {}, + "headerColumnResizeHandleColor": {}, + "headerColumnResizeHandleHeight": {}, + "headerColumnResizeHandleWidth": {}, + "headerTextColor": {} + }, + "icons": { + "meta": { + "displayName": "Icons", + "page": { + "name": "Custom Icons", + "url": "./custom-icons/" + } + }, + "dragHandleColor": {}, + "iconButtonActiveBackgroundColor": {}, + "iconButtonActiveColor": {}, + "iconButtonActiveIndicatorColor": {}, + "iconButtonBackgroundColor": {}, + "iconButtonBackgroundSpread": {}, + "iconButtonBorderRadius": {}, + "iconButtonColor": {}, + "iconButtonHoverBackgroundColor": {}, + "iconButtonHoverColor": {}, + "iconColor": {} + }, + "sidebar": { + "meta": { + "displayName": "Sidebar", + "description": "Style [Tool Panels](./tool-panel/), see also [Theming: Customising Tool Panels](./theming-tool-panels/)" + }, + "sideBarBackgroundColor": {}, + "sideBarPanelWidth": {}, + "sideButtonBackgroundColor": {}, + "sideButtonBarBackgroundColor": {}, + "sideButtonBarTopPadding": {}, + "sideButtonBorder": {}, + "sideButtonHoverBackgroundColor": {}, + "sideButtonHoverTextColor": {}, + "sideButtonLeftPadding": {}, + "sideButtonRightPadding": {}, + "sideButtonSelectedBackgroundColor": {}, + "sideButtonSelectedBorder": {}, + "sideButtonSelectedTextColor": {}, + "sideButtonSelectedUnderlineColor": {}, + "sideButtonSelectedUnderlineTransitionDuration": {}, + "sideButtonSelectedUnderlineWidth": {}, + "sideButtonTextColor": {}, + "sideButtonVerticalPadding": {}, + "toolPanelSeparatorBorder": {} + }, + "inputs": { + "meta": { + "displayName": "Inputs", + "page": { + "name": "Customising Inputs & Widgets", + "url": "./theming-widgets/" + } + }, + "focusErrorShadow": {}, + "focusShadow": {}, + "invalidColor": {}, + "inputBackgroundColor": {}, + "inputBorder": {}, + "inputBorderRadius": {}, + "inputDisabledBackgroundColor": {}, + "inputDisabledBorder": {}, + "inputDisabledTextColor": {}, + "inputFocusBackgroundColor": {}, + "inputFocusBorder": {}, + "inputFocusShadow": {}, + "inputFocusTextColor": {}, + "inputHeight": {}, + "inputIconColor": {}, + "inputInvalidBackgroundColor": {}, + "inputInvalidBorder": {}, + "inputInvalidTextColor": {}, + "inputPaddingStart": {}, + "inputPlaceholderTextColor": {}, + "inputTextColor": {} + }, + "pickers": { + "meta": { + "displayName": "Pickers & Selects", + "page": { + "name": "Customising Inputs & Widgets", + "url": "./theming-widgets/" + } + }, + "pickerButtonBackgroundColor": {}, + "pickerButtonBorder": {}, + "pickerButtonFocusBackgroundColor": {}, + "pickerButtonFocusBorder": {}, + "pickerListBackgroundColor": {}, + "pickerListBorder": {}, + "selectCellBackgroundColor": {}, + "selectCellBorder": {} + }, + "buttons": { + "meta": { + "displayName": "Buttons", + "page": { + "name": "Customising Inputs & Widgets", + "url": "./theming-widgets/" + } + }, + "buttonActiveBackgroundColor": {}, + "buttonActiveBorder": {}, + "buttonActiveTextColor": {}, + "buttonBackgroundColor": {}, + "buttonBorder": {}, + "buttonBorderRadius": {}, + "buttonDisabledBackgroundColor": {}, + "buttonDisabledBorder": {}, + "buttonDisabledTextColor": {}, + "buttonFontWeight": {}, + "buttonHorizontalPadding": {}, + "buttonHoverBackgroundColor": {}, + "buttonHoverBorder": {}, + "buttonHoverTextColor": {}, + "buttonTextColor": {}, + "buttonVerticalPadding": {} + }, + "checkboxes": { + "meta": { + "displayName": "Checkboxes & Radio Buttons", + "page": { + "name": "Customising Inputs & Widgets", + "url": "./theming-widgets/" + } + }, + "checkboxBorderRadius": {}, + "checkboxBorderWidth": {}, + "checkboxCheckedBackgroundColor": {}, + "checkboxCheckedBorderColor": {}, + "checkboxCheckedShapeColor": {}, + "checkboxCheckedShapeImage": {}, + "checkboxIndeterminateBackgroundColor": {}, + "checkboxIndeterminateBorderColor": {}, + "checkboxIndeterminateShapeColor": {}, + "checkboxIndeterminateShapeImage": {}, + "checkboxUncheckedBackgroundColor": {}, + "checkboxUncheckedBorderColor": {}, + "radioCheckedShapeImage": {} + }, + "toggleButtons": { + "meta": { + "displayName": "Toggle Buttons", + "page": { + "name": "Customising Inputs & Widgets", + "url": "./theming-widgets/" + } + }, + "toggleButtonHeight": {}, + "toggleButtonOffBackgroundColor": {}, + "toggleButtonOnBackgroundColor": {}, + "toggleButtonSwitchBackgroundColor": {}, + "toggleButtonSwitchInset": {}, + "toggleButtonWidth": {} + }, + "menusAndPopups": { + "meta": { + "displayName": "Menus & Popups", + "description": "Style menus like the [Context Menu](./context-menu/) and [Column Menu](./column-menu/), see also [Theming: Customising Menus & Popups](./theming-popups/)" + }, + "cardShadow": {}, + "dropdownShadow": {}, + "menuBackgroundColor": {}, + "menuBorder": {}, + "menuSeparatorColor": {}, + "menuShadow": {}, + "menuTextColor": {}, + "modalOverlayBackgroundColor": {}, + "popupShadow": {} + }, + "tooltips": { + "meta": { + "displayName": "Tooltips", + "page": { + "name": "Tooltips", + "url": "./tooltips/" + } + }, + "tooltipBackgroundColor": {}, + "tooltipBorder": {}, + "tooltipErrorBackgroundColor": {}, + "tooltipErrorBorder": {}, + "tooltipErrorTextColor": {}, + "tooltipTextColor": {} + }, + "panels": { + "meta": { + "displayName": "Panels & Dialogs", + "page": { + "name": "Theming: Customising Menus & Popups", + "url": "./theming-popups/" + } + }, + "dialogBorder": {}, + "dialogShadow": {}, + "panelBackgroundColor": {}, + "panelTitleBarBackgroundColor": {}, + "panelTitleBarBorder": {}, + "panelTitleBarFontFamily": {}, + "panelTitleBarFontSize": {}, + "panelTitleBarFontWeight": {}, + "panelTitleBarHeight": {}, + "panelTitleBarIconColor": {}, + "panelTitleBarTextColor": {} + }, + "tabs": { + "meta": { + "displayName": "Tabs", + "page": { + "name": "Theming: Customising Tool Panels", + "url": "./theming-tool-panels/" + } + }, + "tabBackgroundColor": {}, + "tabBarBackgroundColor": {}, + "tabBarBorder": {}, + "tabBarHorizontalPadding": {}, + "tabBarTopPadding": {}, + "tabBottomPadding": {}, + "tabHorizontalPadding": {}, + "tabHoverBackgroundColor": {}, + "tabHoverTextColor": {}, + "tabSelectedBackgroundColor": {}, + "tabSelectedBorderColor": {}, + "tabSelectedBorderWidth": {}, + "tabSelectedTextColor": {}, + "tabSelectedUnderlineColor": {}, + "tabSelectedUnderlineTransitionDuration": {}, + "tabSelectedUnderlineWidth": {}, + "tabSpacing": {}, + "tabTextColor": {}, + "tabTopPadding": {} + }, + "editing": { + "meta": { + "displayName": "Editing", + "page": { + "name": "Cell Editing", + "url": "./cell-editing/" + } + }, + "cellBatchEditBackgroundColor": {}, + "cellBatchEditTextColor": {}, + "cellEditingBorder": {}, + "cellEditingShadow": {}, + "fullRowEditInvalidBackgroundColor": {}, + "rowBatchEditBackgroundColor": {}, + "rowBatchEditTextColor": {} + }, + "columnDrop": { + "meta": { + "displayName": "Column Drop", + "description": "The Column drop component is used in the [Columns Tool Panel](./tool-panel-columns/) and [Row Group Panel](./grouping-group-panel/)." + }, + "columnDropCellBackgroundColor": {}, + "columnDropCellBorder": {}, + "columnDropCellDragHandleColor": {}, + "columnDropCellTextColor": {} + }, + "advancedFilter": { + "meta": { + "displayName": "Advanced Filter", + "page": { + "name": "Advanced Filter", + "url": "./filter-advanced/" + } + }, + "advancedFilterBuilderButtonBarBorder": {}, + "advancedFilterBuilderColumnPillColor": {}, + "advancedFilterBuilderIndentSize": {}, + "advancedFilterBuilderJoinPillColor": {}, + "advancedFilterBuilderOptionPillColor": {}, + "advancedFilterBuilderValuePillColor": {} + }, + "find": { + "meta": { + "displayName": "Find", + "page": { + "name": "Find", + "url": "./find/" + } + }, + "findActiveMatchBackgroundColor": {}, + "findActiveMatchColor": {}, + "findMatchBackgroundColor": {}, + "findMatchColor": {} + }, + "filterPanel": { + "meta": { + "displayName": "Filter Panel", + "page": { + "name": "Filters Tool Panel", + "url": "./tool-panel-filters/" + } + }, + "columnSelectIndentSize": {}, + "filterPanelApplyButtonBackgroundColor": {}, + "filterPanelApplyButtonColor": {}, + "filterPanelCardSubtleColor": {}, + "filterPanelCardSubtleHoverColor": {}, + "filterToolPanelGroupIndent": {}, + "setFilterIndentSize": {} + }, + "dragAndDrop": { + "meta": { + "displayName": "Drag & Drop", + "description": "Row dragging, column dragging, and data drag & drop" + }, + "columnDragIndicatorColor": {}, + "columnDragIndicatorWidth": {}, + "dragAndDropImageBackgroundColor": {}, + "dragAndDropImageBorder": {}, + "dragAndDropImageNotAllowedBorder": {}, + "dragAndDropImageShadow": {}, + "rowDragIndicatorColor": {}, + "rowDragIndicatorWidth": {} + }, + "formulaBar": { + "meta": { + "displayName": "Formula Bar", + "page": { + "name": "Formulas", + "url": "./formulas/" + } + }, + "formulaToken1BackgroundColor": {}, + "formulaToken1Border": {}, + "formulaToken1Color": {}, + "formulaToken2BackgroundColor": {}, + "formulaToken2Border": {}, + "formulaToken2Color": {}, + "formulaToken3BackgroundColor": {}, + "formulaToken3Border": {}, + "formulaToken3Color": {}, + "formulaToken4BackgroundColor": {}, + "formulaToken4Border": {}, + "formulaToken4Color": {}, + "formulaToken5BackgroundColor": {}, + "formulaToken5Border": {}, + "formulaToken5Color": {}, + "formulaToken6BackgroundColor": {}, + "formulaToken6Border": {}, + "formulaToken6Color": {}, + "formulaToken7BackgroundColor": {}, + "formulaToken7Border": {}, + "formulaToken7Color": {} + }, + "statusBar": { + "meta": { + "displayName": "Status Bar", + "page": { + "name": "Status Bar", + "url": "./status-bar/" + } + }, + "statusBarLabelColor": {}, + "statusBarLabelFontWeight": {}, + "statusBarValueColor": {}, + "statusBarValueFontWeight": {} + }, + "charts": { + "meta": { + "displayName": "Integrated Charts", + "page": { + "name": "Integrated Charts", + "url": "./integrated-charts/" + } + }, + "chartMenuLabelColor": {}, + "chartMenuPanelWidth": {}, + "colorPickerColorBorderRadius": {}, + "colorPickerThumbBorderWidth": {}, + "colorPickerThumbSize": {}, + "colorPickerTrackBorderRadius": {}, + "colorPickerTrackSize": {}, + "rangeSelectionChartBackgroundColor": {}, + "rangeSelectionChartCategoryBackgroundColor": {} + } +} diff --git a/documentation/ag-grid-docs/src/content/api-nav/nav.json b/documentation/ag-grid-docs/src/content/api-nav/nav.json index 03588648358..ed5ece2aa55 100644 --- a/documentation/ag-grid-docs/src/content/api-nav/nav.json +++ b/documentation/ag-grid-docs/src/content/api-nav/nav.json @@ -33,6 +33,11 @@ "title": "API Reference", "path": "grid-api" }, + { + "type": "item", + "title": "Theme Parameters", + "path": "theming-api" + }, { "type": "item", "title": "Custom Components", diff --git a/documentation/ag-grid-docs/src/content/docs/theming-api/index.mdoc b/documentation/ag-grid-docs/src/content/docs/theming-api/index.mdoc new file mode 100644 index 00000000000..a4e2e8c2572 --- /dev/null +++ b/documentation/ag-grid-docs/src/content/docs/theming-api/index.mdoc @@ -0,0 +1,17 @@ +--- +title: "Theme Parameters Reference" +description: "Complete reference for all AG Grid theme parameters used to configure colours, fonts, borders, spacing and more." +--- + +This page documents all theme parameters available when using the [Theming API](./theming-parameters/). + +Parameters are set using the `theme.withParams()` method: + +```js +const myTheme = themeQuartz.withParams({ + accentColor: 'red', + spacing: 12, +}); +``` + +{% apiDocumentation source="theming-api/properties.json" /%} diff --git a/documentation/ag-grid-docs/src/utils/pages.ts b/documentation/ag-grid-docs/src/utils/pages.ts index a9b0301f090..cf3d040d1e6 100644 --- a/documentation/ag-grid-docs/src/utils/pages.ts +++ b/documentation/ag-grid-docs/src/utils/pages.ts @@ -54,6 +54,7 @@ export const FILES_PATH_MAP: Record = { 'reference/grid-options.AUTO.json': 'dist/documentation/reference/grid-options.AUTO.json', 'reference/interfaces.AUTO.json': 'dist/documentation/reference/interfaces.AUTO.json', 'reference/row-node.AUTO.json': 'dist/documentation/reference/row-node.AUTO.json', + 'reference/theming-api.AUTO.json': 'dist/documentation/reference/theming-api.AUTO.json', // Community modules '@ag-grid-community/locale/dist/**': 'community-modules/locale/dist/**/*.{cjs,js,map}', diff --git a/documentation/update-algolia-indices/src/generators/api-refs.ts b/documentation/update-algolia-indices/src/generators/api-refs.ts index 63d8f0b9742..85ba1080d2b 100644 --- a/documentation/update-algolia-indices/src/generators/api-refs.ts +++ b/documentation/update-algolia-indices/src/generators/api-refs.ts @@ -91,6 +91,11 @@ const getFirstLevelProperties = (typeName: string): string[] => { return Object.keys(interfaceData).filter((key) => !IGNORE_FIELDS.has(key)); }; +const paramToVariableName = (paramName: string): string => { + const kebabCase = paramName.replace(/[A-Z]|\d+/g, (m) => `-${m}`).toLowerCase(); + return `--ag-${kebabCase}`; +}; + const getCodeWordsForApiProperty = (data: APIPropertyRefSource, normalizedText: string): string[] => { const docInterfaces = getDocInterfaces(); const allWords: string[] = []; @@ -151,7 +156,7 @@ export const parseApiPageData = (details: APIPageData): AlgoliaRecord[] => { const file = fs.readFileSync(propertiesFileUrl, 'utf8'); const { _config_, ...sections } = JSON.parse(file); if (!_config_) return []; // if no config, wrong type of file. - const { codeSrc } = _config_; + const { codeSrc, codeWordsMode } = _config_; if (!codeSrc) return []; // if no src, wrong type of file. const referenceFile = fs.readFileSync(`${API_REFERENCE_DIR}/${codeSrc}`, 'utf8'); @@ -179,11 +184,14 @@ export const parseApiPageData = (details: APIPageData): AlgoliaRecord[] => { const text = description ?? data.meta.comment; const normalizedText = text?.replace(/\[([^\]]+)\][^)]+\)/g, '$1'); - // Extract all code words (text + type names + nested properties) - // Skip if property/method name is excluded - const codeWords = TYPE_PROPERTY_INDEXING[propertyKey] - ? [] - : getCodeWordsForApiProperty(data, normalizedText); + let codeWords: string[]; + if (codeWordsMode === 'cssVariable') { + codeWords = [paramToVariableName(propertyKey)]; + } else if (TYPE_PROPERTY_INDEXING[propertyKey] === 'never') { + codeWords = []; + } else { + codeWords = getCodeWordsForApiProperty(data, normalizedText); + } records.push({ source: 'api', diff --git a/external/ag-shared/.gitrepo b/external/ag-shared/.gitrepo index 17de75a9a89..4a57bb94e2f 100644 --- a/external/ag-shared/.gitrepo +++ b/external/ag-shared/.gitrepo @@ -6,7 +6,7 @@ [subrepo] remote = https://github.com/ag-grid/ag-shared.git branch = latest - commit = ae9edea620feed79c99d07134b17f3d12f218c78 - parent = 4f8bfc807bc0f0bda0150626c53a43c4369c8fcb + commit = cde57a75f6011deff9c625d6d017061913e81cd6 + parent = 08db58bfb47079d97c285e1736efa289a81e0b9a method = rebase cmdver = 0.4.9 diff --git a/external/ag-shared/prompts/agents/docs-example-browser-tester.md b/external/ag-shared/prompts/agents/docs-example-browser-tester.md new file mode 100644 index 00000000000..3e79a4bc53d --- /dev/null +++ b/external/ag-shared/prompts/agents/docs-example-browser-tester.md @@ -0,0 +1,85 @@ +--- +name: docs-example-browser-tester +targets: ['*'] +description: 'Browser-tests a single documentation example at its direct URL. Takes screenshots, tests interactive controls, checks console errors. One agent per example, spawned in parallel from docs-review.' +claudecode: + model: haiku + tools: + - Read + - Grep + - Glob + - Write + - mcp__claude-in-chrome__tabs_context_mcp + - mcp__claude-in-chrome__tabs_create_mcp + - mcp__claude-in-chrome__navigate + - mcp__claude-in-chrome__computer + - mcp__claude-in-chrome__read_page + - mcp__claude-in-chrome__find + - mcp__claude-in-chrome__read_console_messages + - mcp__claude-in-chrome__resize_window + - mcp__claude-in-chrome__get_page_text +--- + +You are a browser testing agent that verifies a single documentation example renders and behaves correctly. You are delegated work from the main docs-review agent ā€” one instance of you is spawned per example. + +## Input + +You receive context for **one example**: + +- `name` ā€” example identifier +- `url` ā€” direct standalone URL (not embedded in docs page) +- `docClaims` ā€” what the documentation says the example demonstrates +- `expectedControls` ā€” interactive controls expected above the grid (buttons, dropdowns, etc.) +- `expectedBehaviours` ā€” behaviours to verify when interacting with controls +- **Browser Testing Tips Path** (optional) ā€” file path to product-specific testing guidance +- **Reports Directory** ā€” where to save screenshots + +## Workflow + +1. **Read browser testing tips** if a path is provided. +2. **Establish browser session**: call `tabs_context_mcp` to connect, then create a new tab with `tabs_create_mcp`. +3. **Navigate** to the example's direct URL. The example renders full-viewport with no docs page chrome or iframe wrapper. +4. **Wait for the page to load**, then take a screenshot of the **default state**. +5. **Identify interactive controls** (buttons, dropdowns, inputs) above or around the grid. Use `find` or `read_page` to locate them. +6. **For each interactive control**: + - Click the control. + - Wait briefly for the result. + - Take a screenshot of the **result state**. +7. **Check the browser console** for errors using `read_console_messages`. Ignore known warnings: + - Enterprise licence messages + - Development mode warnings +8. **Return findings** for this example. + +## Output Format + +Return a structured report for the example: + +``` +#### [Example Name] - Browser Verification +**URL**: [direct example URL] + +[PASSED] **Renders correctly**: [description of what was verified] +[PASSED] **Interactive control [name]**: Clicking [control] produced [expected result] + +[CRITICAL] **Rendering Issue**: +- **Documentation claims**: [What docs say] +- **Actual rendering**: [What was observed] +- **Screenshot**: [reference to screenshot file] + +[WARNING] **Console Errors**: [list any unexpected errors] +``` + +Use these status indicators: + +- `[PASSED]` ā€” verified and matches documentation claims +- `[WARNING]` ā€” minor issue or unexpected console message, does not affect functionality +- `[CRITICAL]` ā€” rendering failure, broken interaction, or behaviour contradicting documentation + +## Important Notes + +- You handle exactly **one example**. Do not navigate to other examples or the docs page. +- The example at its direct URL renders full-viewport. There is no iframe or surrounding docs page ā€” interactive controls are directly accessible. +- Console messages come only from the example itself, not the docs page. +- Screenshots capture the complete example without docs page chrome. +- If the example fails to load, report it as `[CRITICAL]`. +- Do not navigate to the docs page. Only use the direct example URL provided. diff --git a/external/ag-shared/prompts/commands/context/remember.md b/external/ag-shared/prompts/commands/context/remember.md deleted file mode 100644 index 8c5682339a2..00000000000 --- a/external/ag-shared/prompts/commands/context/remember.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -targets: ['*'] -description: 'Extract and persist learnings from conversations as agentic memory' -fork: true ---- - -# Remember - -Extract decisions, patterns, and learnings from the current conversation and persist them as agentic memory. - -## When to Use - -- After resolving a non-obvious issue with a specific approach -- When discovering a pattern that should be reused -- When user corrects agent behaviour or preferences -- After clarifying how existing rules should be interpreted - -## Memory Extraction - -Review the conversation to identify: - -1. **Decisions** - Specific choices made (e.g., "use X approach instead of Y") -2. **Corrections** - Mistakes caught and how to avoid them -3. **Patterns** - Reusable approaches that worked well -4. **Preferences** - User/project preferences revealed -5. **Clarifications** - Ambiguous rules made concrete - -For each candidate, extract: -- The core learning (1-2 sentences) -- Context where it applies -- Why it matters - -## Classification - -Determine the best location for each memory: - -| Type | Location | When | -|------|----------|------| -| Domain rule | `.rulesync/rules/{domain}.md` | Topic-specific guidance | -| Command enhancement | `.rulesync/commands/{cmd}.md` | Workflow-specific | -| Skill update | `external/prompts/skills/{skill}/` | Skill-scoped learning | -| New rule file | `.rulesync/rules/{new}.md` | Distinct topic, 3+ guidelines | - -**Constraints**: -- **Never update root files directly** - `CLAUDE.md`, `AGENTS.md`, and files with `root: true` frontmatter are managed separately. If a memory belongs there, recommend creating/updating a non-root rule that gets referenced instead. -- **Prefer existing files** - only create new files when the topic is clearly distinct and has sufficient content. - -## Interactive Presentation - -For each memory candidate, present to user: - -### Memory N of M - -**Learning**: [The extracted insight] - -**Recommended location**: `path/to/file.md` ā†’ Section Name - -**Options**: -1. āœ… Add to recommended location -2. šŸ“ Add to different location (specify) -3. āœļø Rephrase the learning -4. ā­ļø Skip this memory - -Use AskUserQuestion with these options. Wait for user response before proceeding. - -## Execution - -For approved memories: - -1. **Read** the target file to understand current structure -2. **Locate** the appropriate section (or create if needed) -3. **Format** the memory to match file conventions: - - Rules: Use `-` bullet points, match existing tone - - Commands: Integrate into relevant phase/section -4. **Write** the update using Edit tool -5. **Confirm** the change to user - -## Output - -After processing all memories, summarise: - -``` -## Memory Update Summary - -Added: N memories -Skipped: M memories -Files modified: -- path/to/file1.md (section updated) -- path/to/file2.md (new section added) -``` - -## Constraints - -- **Never update root files** - Do not modify `CLAUDE.md`, `AGENTS.md`, or any file with `root: true` in frontmatter. These are managed separately. Instead, create or update a non-root rule file that can be referenced. -- Keep memories atomic - one concept per update -- Match the writing style of the target file -- If unsure about location, ask user rather than guess -- Memories should be actionable, not just observations diff --git a/external/ag-shared/prompts/commands/docs/_docs-review-core.md b/external/ag-shared/prompts/commands/docs/_docs-review-core.md new file mode 100644 index 00000000000..4444deda44c --- /dev/null +++ b/external/ag-shared/prompts/commands/docs/_docs-review-core.md @@ -0,0 +1,440 @@ +# Documentation Review Core Methodology + +This file contains the shared documentation review methodology. It is included by product-specific wrapper prompts that provide configuration (paths, conventions, resolution rules). + +## Required Product Configuration + +The product wrapper that references this file MUST define these sections (referenced by exact name below): + +- **Input Requirements** ā€” documentation page path pattern, dev URL +- **File Resolution Rules** ā€” table mapping documentation references to TypeScript definition files +- **Implementation Resolution Rules** ā€” table mapping features to source implementation files +- **Example Path Pattern** ā€” directory layout for examples +- **Exceptions File Path** ā€” location of the per-page exceptions file +- **Output Paths** ā€” where review plans, reports, and summaries are written +- **Default Value Verification Hierarchy** ā€” how runtime defaults are resolved in the product +- **Product-Specific Conventions** ā€” accepted patterns, known pitfalls, enablement conventions + +Optional sections: + +- **Orchestration Indicator** ā€” if the product has a batch orchestration script, name it here so Strict Mode can be detected +- **Browser Testing Tips** ā€” file path to product-specific browser testing guidance, read at the start of browser testing +- **Example Direct URL Pattern** ā€” URL template with `${pageName}` and `${exampleName}` placeholders for opening examples at standalone direct URLs (no iframe, no docs page chrome). When configured, browser testing of examples is delegated to a sub-agent. + +## Execution Mode Detection + +Check for any of these indicators: + +- "EXECUTION CONTEXT: ORCHESTRATED" in the prompt +- Session ID provided +- Invoked via the orchestrator script named in **Orchestration Indicator** (if provided) + +**If found**: **STRICT MODE** - All MCP tools REQUIRED. If ANY tool is missing, STOP immediately with error message: `ERROR: Cannot proceed in orchestrated mode - missing required MCP tool [name]`. Do NOT attempt review or fallbacks. + +**If not found**: Proceed with the layered review approach described below. + +## Review Approach: Static Analysis + Browser Testing + +Every review performs **static analysis** ā€” reading files, validating APIs, checking examples against TypeScript definitions. This always happens regardless of tool availability. + +When browser tools (claude-in-chrome) are available, **browser testing is additionally performed** on top of static analysis. Browser testing verifies rendering, interactive behaviour, and visual correctness that static analysis cannot check. + +### Browser Availability Check + +At the **start of Phase 2**, determine browser availability: + +1. Call `mcp__claude-in-chrome__tabs_context_mcp` to test browser connectivity. +2. If the call **succeeds**: browser testing is **MANDATORY** for this review, in addition to static analysis. +3. If the call **fails** or the tool does not exist: note the limitation and proceed with static analysis only. Display the warning below. + +IMPORTANT: When `tabs_context_mcp` succeeds, browser testing is REQUIRED in addition to static analysis. DO NOT skip browser testing. DO NOT report "[SKIPPED] VISUAL TESTING" when browser tools are available. DO NOT assume browser tools are unavailable without first calling `tabs_context_mcp`. + +### Browser Unavailable Warning Template + +Display this warning only when `tabs_context_mcp` fails or is not available: + +``` +[WARNING] BROWSER TOOLS UNAVAILABLE + +Missing capabilities: +- Browser automation (claude-in-chrome) + +Limitations: +- Static code analysis only for examples +- No automated screenshots +- No runtime behavior validation +- No interactive testing + +Still included: +- Full API and TypeScript validation +- Configuration consistency checking +- Static example code analysis +- Documentation accuracy assessment +``` + +## Three-Phase Review Process + +### Phase 1: Create Review Plan + +**Goal**: Analyse documentation and create structured validation plan using mechanical file resolution. + +#### Step 1: Discover Files to Review + +**A. Read documentation page**: Use the path pattern from **Input Requirements** in the product configuration. + +**B. Extract API surface systematically**: + +1. **Scan for code blocks** containing configuration objects to extract property names +2. **Extract interface references** from docs (look for product-specific interface naming patterns) +3. **List all example references** (pattern: ` **Default Value Verification**: When checking defaults, always verify against the hierarchy described in the **Default Value Verification Hierarchy** in the product configuration. Theme/module defaults override decorator defaults and represent actual runtime behaviour. + + - Verify APIs against TypeScript definitions using paths from **File Resolution Rules** + - Check implementations using paths from **Implementation Resolution Rules** + - Validate default values using the hierarchy from product configuration + - Verify code snippets work correctly + - Document findings with: + - Status indicators: `[CRITICAL]`, `[WARNING]`, or `[PASSED]` + - Specific file:line locations + - Code examples showing incorrect vs correct + - For defaults: Show all layers of the verification hierarchy + +4. **Example Testing ā€” Static Analysis** (always performed): + + For each example, perform static analysis: + + - Read source files from the **Example Path Pattern** + - Extract documentation claims about the example + - Validate: configuration consistency, API usage, property validation, data compatibility, best practices + - Report format: + + ``` + #### [Example Name] - Static Analysis + **Location**: `_examples/[example-name]/` + + [PASSED] **Configuration Verified**: [list validated configurations] + + [CRITICAL] **Configuration Issues**: + - **Issue**: [Specific mismatch] + - **Documentation claims**: [What docs say] + - **Actual code**: [What's in example] + - **Fix Required**: [Specific action] + ``` + +5. **Example Testing ā€” Browser Verification** (when browser available): + + **If the product configuration includes an Example Direct URL Pattern**, delegate browser testing to parallel `docs-example-browser-tester` sub-agents (one per example): + + 1. **Construct direct example URLs** by substituting `${pageName}` and `${exampleName}` into the URL pattern for each example identified in the review plan. + 2. **Prepare testing context** ā€” for each example, assemble: + - `name`: the example identifier + - `url`: the direct standalone URL + - `docClaims`: what the documentation says the example demonstrates + - `expectedControls`: interactive controls expected (from static analysis in step 4) + - `expectedBehaviours`: behaviours to verify when interacting + 3. **Spawn one `docs-example-browser-tester` sub-agent per example** via parallel Task tool calls in a single message (haiku model). Each sub-agent receives context for its single example only, plus the **Browser Testing Tips** file path (if configured) and the reports directory path. + + IMPORTANT: Issue ALL Task calls in a SINGLE message to run them in parallel. + Do NOT spawn one agent, wait for it to finish, then spawn the next. + Example pattern for a page with 3 examples: + + ``` + Task call 1: { subagent_type: "docs-example-browser-tester", prompt: "Test example 'foo' at https://...foo/vanilla ..." } + Task call 2: { subagent_type: "docs-example-browser-tester", prompt: "Test example 'bar' at https://...bar/vanilla ..." } + Task call 3: { subagent_type: "docs-example-browser-tester", prompt: "Test example 'baz' at https://...baz/vanilla ..." } + ``` + + Each Task call must contain the full testing context for exactly ONE example + (name, url, docClaims, expectedControls, expectedBehaviours). Do not combine + multiple examples into a single Task call. + 4. **Collect results** from all sub-agents and integrate into the report under each example's section. + + **If Example Direct URL Pattern is NOT configured**, perform inline browser testing (fallback): + + For each example identified in the review plan: + + 1. Scroll to the example on the page (scroll over prose text or margins, NOT over grid iframes ā€” grids capture scroll events) + 2. Take a screenshot of the example in its default state + 3. Identify interactive controls (buttons, dropdowns) rendered above the grid iframe + 4. Click each documented interactive control and screenshot the result state + 5. Compare the rendered output against documentation claims + 6. Check browser console for errors after interactions (ignore known warnings like licence messages) + + Report format (used by both approaches): + + ``` + #### [Example Name] - Browser Verification + **URL**: [direct example URL or dev URL with anchor] + + [PASSED] **Renders correctly**: [description of what was verified] + [PASSED] **Interactive control [name]**: Clicking [control] produced [expected result] + + [CRITICAL] **Rendering Issue**: + - **Documentation claims**: [What docs say] + - **Actual rendering**: [What was observed] + - **Screenshot**: [reference to screenshot file] + + [WARNING] **Console Errors**: [list any unexpected errors] + ``` + +6. **Visual & Interaction Testing** (when browser available): + + Test interactive features described in the documentation beyond individual examples: + + 1. Test page-level interactive features (e.g., theme switchers, framework selectors) + 2. Test any documented keyboard interactions or accessibility features + 3. Verify cross-references and internal links navigate correctly + 4. Take screenshots as evidence for each test + 5. Check browser console for errors throughout testing + 6. Save screenshots to the reports directory for this page + +7. **Content Quality** (always performed): + - Completeness of feature coverage + - Accuracy against code analysis (static and browser-based if available) + - Missing documentation for discovered features + +**Output**: Write to the reports path specified in **Output Paths** (see Report Structure below). + +### Phase 3: Generate Summary + +**Goal**: Aggregate findings from all reviewed pages. + +Process page reports in batches to avoid context limits: + +1. Process ~10 pages per batch ā†’ temporary `batch-summary-{n}.json` +2. Aggregate batch summaries ā†’ final report +3. Identify patterns and prioritise recommendations + +**Output**: Write to the summary path specified in **Output Paths**. + +## Report Structure Requirements (Phase 2) + +All reports must include these sections in order. Use the specified structure and include all required elements. + +### 1. Executive Summary + +Required elements: + +- Brief assessment of page +- Browser testing status: whether browser tools were available and used +- Overall status: `[CRITICAL ISSUES]`, `[ISSUES FOUND]`, or `[ALL PASSED]` +- Issue counts by category: Technical Accuracy, Example Consistency (static + browser if available), Visual/Interaction (or SKIPPED if browser unavailable), Content Quality + +### 2. Review Limitations (if browser unavailable) + +Include this section only when `tabs_context_mcp` failed or was not available. List what was skipped (browser testing, screenshots, interactions) and what was completed (static analysis, configuration verification, API validation). + +### 3. Known Exceptions + +List exceptions from the exceptions file (see **Exceptions File Path** in product configuration) if any exist, or note if no exceptions file found. + +### 4. Technical Accuracy Issues + +Structure each finding as: + +- Status indicator: `[PASSED]`, `[WARNING]`, or `[CRITICAL]` +- Specific file:line reference +- Code comparison (incorrect ā†’ correct) +- Implementation file reference + +Example: + +``` +[CRITICAL] **Default Value Mismatch** at `index.mdoc:45` +- Docs claim: `spacing: 10` (default) +- Decorator default: `spacing: number = 1` (Properties.ts:95) +- Theme/module default: `spacing: 20` (Module.ts:51) <-- Actual runtime default +- TypeScript comment: `spacing: 10` (Options.ts:74) <-- Stale +- Fix: Update documentation and TypeScript comment to reflect runtime default of 20 +``` + +### 5. Example Consistency Issues + +Structure findings by example with clear headers. Include appropriate status labels (CRITICAL FAILURE, DOCUMENTATION MISMATCH, etc.). Provide specific fix instructions. + +Always include static analysis findings for every example. When browser testing was performed, additionally include browser verification findings (rendering, interaction results, screenshots) for each example. + +### 6. Visual and Interaction Testing Results + +- **Browser available**: Reference specific screenshots as evidence (e.g., "See `reports/screenshots/tooltip-hover.png`"). Include interaction test results and console error checks. +- **Browser unavailable**: Note "[SKIPPED] VISUAL TESTING ā€” `tabs_context_mcp` was not available or failed". Only use this marker when browser tools were genuinely unavailable. +- List any console errors found during testing + +### 7. Content Quality Issues + +Document: + +- Missing property documentation +- Incomplete feature coverage +- Unclear explanations +- Gaps between implementation and documentation + +### 8. Recommendations + +Organise by priority with specific fix instructions: + +``` +### High Priority (Critical Fixes Required) +1. **[Specific Issue]**: + - [Specific fix instruction] + - Update file: `[exact file path]` at line [X] + +### Medium Priority +[List medium priority fixes] + +### Low Priority +[List low priority improvements] +``` + +### 9. Summary + +Overall assessment including: + +- Files requiring updates (with full paths) +- Evidence locations (screenshots, test results if available) +- Any limitations due to browser unavailability +- Next steps + +## Documentation Style Principles + +When reviewing documentation, apply these principles to avoid over-documentation: + +### Do NOT Recommend Adding: + +1. **Default values in prose** - Don't add sentences like "The default value is X" unless the default is surprising or essential for understanding. Users can check the API Reference for defaults. + +2. **Redundant enablement explanations** - If something is enabled by default, don't explain how to enable it. Only document how to disable. + + - Bad: "The toolbar can be enabled by setting `enabled: true`, or disabled by setting `enabled: false`" + - Good: "The toolbar is enabled by default. Use `enabled: false` to disable." + +3. **New sections for minor properties** - Not every property needs its own documentation section. Properties like `spacing`, `padding`, or simple numeric values are adequately covered in the API Reference. + +4. **Implementation details** - Don't document internal behaviour like callback return value handling, fallback mechanisms, or edge case handling unless it's essential for correct usage. + +5. **Verbose explanations** - Keep documentation concise. If something can be explained in one sentence, don't use three. + +### Example Titles + +Example titles should describe what the example demonstrates, not just the chart/component type: + +- Bad: "Overlapping Series" (describes the data, not the feature) +- Good: "Simple Highlight" (describes what's being demonstrated) +- Bad: "Bar Chart with Tooltip" (generic) +- Good: "Custom Tooltip Content" (specific feature demonstrated) + +### When Flagging Issues + +Only flag documentation as incomplete if: + +- A **primary feature** is undocumented (not minor styling properties) +- The documentation is **factually incorrect** (wrong API names, broken examples) +- An example **doesn't match** what the documentation claims it shows +- There's a **critical default** that affects common use cases + +Do NOT flag: + +- Missing documentation for every property (that's what API Reference is for) +- Missing default value mentions +- Opportunities to add more detail to already-clear explanations + +## Language Conventions + +Documentation must follow these spelling and language conventions: + +| Content Type | Language | Examples | +| ----------------------------- | ------------------------------------- | ------------------------------------------------------------- | +| **Documentation text** | UK/British English | colour, centre, behaviour, customisation, visualise, minimise | +| **Code comments in examples** | UK/British English | `// Customise the colour` | +| **API option names** | US English (as defined in TypeScript) | `color`, `center`, `behavior` | +| **JSDoc comments** | UK/British English | `/** Customises the series colour. */` | + +**Key Spelling Differences to Check**: + +- colour (UK) vs color (US) - use UK in prose, US in API names +- centre (UK) vs center (US) - use UK in prose, US in API names +- behaviour (UK) vs behavior (US) - use UK in prose +- customisation (UK) vs customization (US) - use UK +- visualise (UK) vs visualize (US) - use UK +- minimise (UK) vs minimize (US) - use UK +- licence (UK noun) vs license (US) - use UK in prose +- organisation (UK) vs organization (US) - use UK +- cancelled (UK) vs canceled (US) - use UK +- labelling (UK) vs labeling (US) - use UK + +**Grammar Checks**: + +- Consistent tense usage (prefer present tense) +- Subject-verb agreement +- Proper punctuation (Oxford comma optional but be consistent) +- Correct use of articles (a/an/the) +- No sentence fragments in explanatory text + +## Tool Usage by Phase + +| Phase | Required Tools | Additional Tools (when browser available) | +| ----------------------------- | -------------- | -------------------------------------------------------------------------------------- | +| Phase 1 | Read, Write | - | +| Phase 2 ā€” Static Analysis | Read, Write | - | +| Phase 2 ā€” Browser Testing | - | Task (parallel per-example docs-example-browser-tester sub-agents), or claude-in-chrome inline as fallback | +| Phase 3 | Read, Write | - | + +## Usage + +1. **Phase 1**: Provide page path ā†’ receive review plan +2. **Phase 2**: Provide page path ā†’ receive detailed report (with static analysis always, browser testing when available) +3. **Phase 3**: Run after all pages reviewed ā†’ receive summary report diff --git a/external/ag-shared/prompts/commands/docs/_release-docs-review-core.md b/external/ag-shared/prompts/commands/docs/_release-docs-review-core.md new file mode 100644 index 00000000000..25bea5c60f5 --- /dev/null +++ b/external/ag-shared/prompts/commands/docs/_release-docs-review-core.md @@ -0,0 +1,941 @@ +# Release Documentation Review Core Methodology + +This file contains the shared release documentation review methodology. It is included by product-specific wrapper prompts that provide configuration (paths, page lists, branch patterns). + +## Required Product Configuration + +The product wrapper that references this file MUST define these sections (referenced by exact name below): + +- **Product** ā€” product name, docs review command name +- **Paths** ā€” docs root, types root, docs file pattern, examples pattern, types file pattern +- **Release Branch Pattern** ā€” branch naming format, discovery command +- **Priority Pages** ā€” high-priority and medium-priority page lists +- **Output Paths** ā€” reports directory, filtered/complete task list paths, summary path +- **Verification Paths** ā€” files to confirm exist after each page review + +## Help + +If the user provides a command option of `help`: + +- Explain how to use this prompt. +- Explain if they are missing any prerequisites or tooling requirements. +- DO NOT proceed, exit the prompt immediately after these steps. + +## Prerequisite - Determine Branches to Compare + +**Checklist:** + +- [ ] Are you given multiple branches as command options? + ā†’ Compare these two as previous and current releases respectively. +- [ ] Are you given a single branch as command option? + ā†’ Compare this branch against the highest-numbered release branch matching the **Release Branch Pattern**. +- [ ] Are you given no command options? + ā†’ Compare the current branch against the highest-numbered release branch, or the previous highest if already on a release branch. + +If you are uncertain about which branches to compare, **halt and ask the user to clarify before continuing.** + +## Task Overview + +Perform a comprehensive documentation review for all docs pages that have been modified or affected by API changes between release branches. This includes: + +1. Directly modified documentation pages +2. Pages containing modified examples +3. Pages referencing modified public APIs + +## Critical Requirements + +**READ THIS FIRST - MANDATORY EXECUTION RULES:** + +### Rule 1: Use SlashCommand Tool for ALL Reviews + +**MANDATORY:** When executing documentation reviews (Step 8), you MUST: + +- Use: `SlashCommand` tool with the docs review command specified in **Product** configuration +- DO NOT: Create custom review prompts for sub-agents +- DO NOT: Perform reviews manually +- DO NOT: Implement alternative review methods + +**Why:** The docs review command follows a standardised three-phase process with specific output formats and quality checks. Custom implementations bypass this standard. + +**Verification:** After each review, confirm the files specified in **Verification Paths** exist. + +### Rule 2: One Page Per Sub-Agent - NO BATCHING + +**MANDATORY:** When spawning sub-agents (Step 8), you MUST: + +- SPAWN: One sub-agent per documentation page +- DO NOT: Batch multiple pages into one sub-agent +- DO NOT: Ask one sub-agent to review 10, 20, or any N>1 pages +- DO NOT: Create "batches" for efficiency + +**Why:** Batching causes: + +1. Inconsistent review depth (later pages get less attention) +2. Context overflow and token exhaustion +3. Non-standard report locations and formats +4. Inability to track per-page completion + +**Correct Pattern:** + +``` +Task 1: Review page-name-1 ā†’ /docs-review page-name-1 +Task 2: Review page-name-2 ā†’ /docs-review page-name-2 +Task 3: Review page-name-3 ā†’ /docs-review page-name-3 +``` + +**Incorrect Pattern:** + +``` +Task 1: Review pages 1-20 ā†’ DO NOT DO THIS +``` + +### Rule 3: Parallel Execution for Efficiency + +**RECOMMENDED:** Launch sub-agents in parallel: + +- USE: Single message with multiple Task tool calls +- LAUNCH: 10-20 agents concurrently (one per page) +- MONITOR: Wait for all agents to complete before aggregating + +**Example:** For 50 pages, launch in 3 waves of ~17 agents each. + +## Workflow + +### Step 1: Identify Previous Release Branch + +Determine the previous release branch to compare against using the checklist above. + +Execute the discovery command from the **Release Branch Pattern** in the product configuration to list recent release branches, then store the branches for comparison: + +```bash +export PREVIOUS_BRANCH= +export CURRENT_BRANCH= +``` + +### Step 2: Identify Modified Documentation Pages + +Find all directly modified documentation files using the **Paths** ā†’ Docs file pattern from the product configuration: + +```bash +# Get list of modified docs files (substitute DOCS_PATH from product config Paths ā†’ Docs root) +git diff --name-only $PREVIOUS_BRANCH $CURRENT_BRANCH -- '${DOCS_PATH}/**/*.mdoc' | \ + grep -E '\.mdoc$' | \ + sed "s|${DOCS_PATH}/||" | \ + sed 's|/index\.mdoc$||' | \ + sort -u > modified-docs.txt + +echo "Found $(wc -l < modified-docs.txt) directly modified documentation pages" +``` + +> **Note**: Replace `${DOCS_PATH}` with the actual docs root path from the product configuration **Paths** section. + +### Step 3: Identify Modified Examples + +Find all modified examples and their associated documentation pages: + +```bash +# Get list of modified examples (substitute DOCS_PATH from product config) +git diff --name-only $PREVIOUS_BRANCH $CURRENT_BRANCH -- '${DOCS_PATH}/**/_examples/**' | \ + grep -E '/_examples/' | \ + sed "s|${DOCS_PATH}/||" | \ + sed 's|/_examples/.*||' | \ + sort -u > examples-docs.txt + +echo "Found $(wc -l < examples-docs.txt) docs pages with modified examples" +``` + +### Step 4: Identify Modified Public APIs + +Analyse changes to public APIs and find documentation pages that reference them: + +```bash +# Get list of modified type files (substitute TYPES_PATH from product config Paths ā†’ Types root) +git diff --name-only $PREVIOUS_BRANCH $CURRENT_BRANCH -- '${TYPES_PATH}/' | \ + grep -E '\.(ts|d\.ts)$' > modified-types.txt + +# Extract modified interface/type names +for file in $(cat modified-types.txt); do + git diff $PREVIOUS_BRANCH $CURRENT_BRANCH -- "$file" | \ + grep -E '^[+-](export )?(interface|type|class|enum) ' | \ + sed -E 's/^[+-](export )?(interface|type|class|enum) ([A-Za-z0-9]+).*/\3/' | \ + sort -u +done > modified-api-names.txt + +# For each modified API, find docs that reference it +> api-affected-docs.txt +for api_name in $(cat modified-api-names.txt); do + grep -r "$api_name" ${DOCS_PATH}/ --include="*.mdoc" | \ + sed "s|${DOCS_PATH}/||" | \ + sed 's|/index\.mdoc:.*||' | \ + sort -u >> api-affected-docs.txt +done + +sort -u api-affected-docs.txt -o api-affected-docs.txt +echo "Found $(wc -l < api-affected-docs.txt) docs pages referencing modified APIs" +``` + +### Step 5: Consolidate Affected Documentation Pages + +Combine all identified pages into a single list: + +```bash +cat modified-docs.txt examples-docs.txt api-affected-docs.txt | \ + sort -u > all-affected-docs.txt + +TOTAL_PAGES=$(wc -l < all-affected-docs.txt) +echo "Total documentation pages requiring review: $TOTAL_PAGES" + +# Keep examples-docs.txt and api-affected-docs.txt for filtering step +rm modified-docs.txt modified-types.txt modified-api-names.txt +``` + +### Step 6: Filter Trivial Changes + +Many documentation changes are trivial formatting standardisation that don't require review. Filter these out to focus on substantive changes. + +First, get diff statistics for all pages: + +```bash +# Get diff statistics for each page (substitute DOCS_PATH from product config) +cat all-affected-docs.txt | while read page; do + file="${DOCS_PATH}/${page}/index.mdoc" + stats=$(git diff $PREVIOUS_BRANCH $CURRENT_BRANCH --shortstat -- "$file" 2>/dev/null) + if [ -n "$stats" ]; then + insertions=$(echo "$stats" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo "0") + deletions=$(echo "$stats" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo "0") + total=$((insertions + deletions)) + echo "$total,$insertions,$deletions,$page" + fi +done | sort -t',' -k1 -nr > /tmp/diff-stats.txt +``` + +Then, categorise changes using Python. The script uses these variables from the product configuration: + +| Script Variable | Product Config Section | +| ---------------------- | ------------------------------------- | +| `DOCS_PATH` | **Paths** ā†’ Docs root | +| `high_priority_pages` | **Priority Pages** ā†’ High priority | +| `medium_priority_pages`| **Priority Pages** ā†’ Medium priority | +| `file_path` template | **Paths** ā†’ Docs root + `/{page}/index.mdoc` | +| Trivial-change patterns| Generic (no product substitution needed) | + +> **Substitute the values below** from the product configuration before executing. + +````python +#!/usr/bin/env python3 +import subprocess +import re + +categories = { + 'SKIP_TRIVIAL': [], + 'SKIP_TEST_NEW': [], + 'REVIEW_NEEDED': [] +} + +# Load pages with example changes +example_pages = set() +try: + with open('examples-docs.txt', 'r') as f: + example_pages = set(line.strip() for line in f if line.strip()) +except FileNotFoundError: + pass + +# Load pages with API changes +api_pages = set() +try: + with open('api-affected-docs.txt', 'r') as f: + api_pages = set(line.strip() for line in f if line.strip()) +except FileNotFoundError: + pass + +def calculate_risk_score(page, total_lines, has_examples, has_api_changes, file_path, prev_branch, curr_branch): + ''' + Calculate risk score (0-100) based on multiple factors. + Higher score = higher priority for review. + ''' + score = 0 + + # Factor 1: Change source (0-40 points) + if has_api_changes: + score += 25 # API changes are high risk + if has_examples: + score += 25 # Example changes are high risk + + # Factor 2: Change magnitude (0-25 points) + if total_lines > 200: + score += 25 + elif total_lines > 100: + score += 20 + elif total_lines > 50: + score += 15 + elif total_lines > 20: + score += 10 + elif total_lines > 0: + score += 5 + + # Factor 3: Content type analysis (0-20 points) + result = subprocess.run( + ['git', 'diff', prev_branch, curr_branch, '--', file_path], + capture_output=True, text=True + ) + diff = result.stdout + + # Check for high-risk content changes + if '{% warning %}' in diff or '{% note %}' in diff: + score += 8 # New warnings/notes are important + if re.search(r'\+##[^#]', diff): # New sections (but not subsections) + score += 12 # New major sections are high priority + + # Factor 4: Page importance (0-15 points) + # SUBSTITUTE these lists from the product configuration Priority Pages section + high_priority_pages = [ + # *** REPLACE with values from product config Priority Pages ā†’ High priority *** + ] + medium_priority_pages = [ + # *** REPLACE with values from product config Priority Pages ā†’ Medium priority *** + ] + + if any(p in page for p in high_priority_pages): + score += 15 + elif any(p in page for p in medium_priority_pages): + score += 10 + elif page.endswith('-test'): + score -= 10 # Test pages are lower priority + + return min(100, max(0, score)) # Clamp to 0-100 + +def is_trivial_change(page, file_path, prev_branch, curr_branch): + ''' + Determine if a change is trivial (formatting only). + Returns True only if ALL changes match known trivial patterns. + Errs on the side of reviewing when uncertain. + ''' + # First check: ignore whitespace-only changes + result_ws = subprocess.run( + ['git', 'diff', '-w', '--ignore-blank-lines', prev_branch, curr_branch, '--', file_path], + capture_output=True, text=True + ) + + # If no diff after ignoring whitespace, it's purely whitespace changes + if not result_ws.stdout.strip(): + return True + + # Get full diff for detailed analysis + result = subprocess.run( + ['git', 'diff', prev_branch, curr_branch, '--', file_path], + capture_output=True, text=True + ) + diff = result.stdout + + # Extract all added lines (excluding diff metadata) + added_lines = [] + for line in diff.split('\n'): + if line.startswith('+') and not line.startswith('+++'): + added_lines.append(line[1:]) # Remove the '+' prefix + + # If no added lines, skip (only deletions) + if not added_lines: + return False + + # Define trivial change patterns (whitelist approach) + trivial_patterns = [ + # Code block metadata additions + r'^\s*```\w+\s+format="snippet"\s*$', + r'^\s*```\w+\s+format="generated"\s*$', + # Frontmatter changes (within --- blocks at file start) + r'^\s*enterprise:\s*(true|false)\s*$', + r'^\s*title:\s*[\'"].*[\'\"]\s*$', + # Empty lines or pure whitespace + r'^\s*$', + # Opening/closing braces for code wrapping (but be conservative) + r'^\s*\{\s*$', + r'^\s*\}\s*$', + ] + + # Check if ALL added lines match trivial patterns + all_trivial = True + for added_line in added_lines: + line_is_trivial = False + for pattern in trivial_patterns: + if re.match(pattern, added_line): + line_is_trivial = True + break + + if not line_is_trivial: + all_trivial = False + break + + # Additional check: look for substantive content changes + has_substantive = ( + '##' in '\n'.join(added_lines) or # New sections + '{% warning %}' in diff or # New warnings + '{% note %}' in diff or # New notes + re.search(r'\+\s*[A-Z][a-z]+.*\w+', diff) # New prose content + ) + + return all_trivial and not has_substantive + +# SUBSTITUTE DOCS_PATH from the product configuration Paths ā†’ Docs root +DOCS_PATH = '*** REPLACE with Paths ā†’ Docs root from product config ***' + +with open('/tmp/diff-stats.txt', 'r') as f: + for line in f: + parts = line.strip().split(',') + total, insertions, deletions, page = int(parts[0]), int(parts[1]), int(parts[2]), parts[3] + + file_path = f"{DOCS_PATH}/{page}/index.mdoc" + + has_examples = page in example_pages + has_api = page in api_pages + + # CRITICAL: Pages with example or API changes must ALWAYS be reviewed + # even if their .mdoc files have trivial or no changes + if has_examples or has_api: + risk_score = calculate_risk_score(page, total, has_examples, has_api, file_path, '$PREVIOUS_BRANCH', '$CURRENT_BRANCH') + categories['REVIEW_NEEDED'].append((risk_score, total, page)) + # Categorize based on .mdoc file changes + elif page.endswith('-test') and deletions == 0: + # New test pages with no deletions + categories['SKIP_TEST_NEW'].append((0, total, page)) + elif is_trivial_change(page, file_path, '$PREVIOUS_BRANCH', '$CURRENT_BRANCH'): + # Only trivial formatting changes + categories['SKIP_TRIVIAL'].append((0, total, page)) + else: + # Everything else needs review (err on the side of reviewing) + risk_score = calculate_risk_score(page, total, has_examples, has_api, file_path, '$PREVIOUS_BRANCH', '$CURRENT_BRANCH') + categories['REVIEW_NEEDED'].append((risk_score, total, page)) + +# Output results sorted by risk score (descending) for REVIEW_NEEDED +for category, pages in categories.items(): + if category == 'REVIEW_NEEDED': + for risk_score, total, page in sorted(pages, key=lambda x: (-x[0], -x[1])): + print(f"{category},{risk_score},{total},{page}") + else: + for risk_score, total, page in pages: + print(f"{category},{risk_score},{total},{page}") +```` + +Save this as `/tmp/categorize.py` and run: + +```bash +python3 /tmp/categorize.py > /tmp/categorized-docs.txt + +# Generate summary with risk score statistics +echo "=== Filtering Results ===" +echo "SKIP_TRIVIAL: $(grep -c '^SKIP_TRIVIAL,' /tmp/categorized-docs.txt) pages" +echo "SKIP_TEST_NEW: $(grep -c '^SKIP_TEST_NEW,' /tmp/categorized-docs.txt) pages" +echo "REVIEW_NEEDED: $(grep -c '^REVIEW_NEEDED,' /tmp/categorized-docs.txt) pages" +echo "" +echo "=== Risk Score Distribution (REVIEW_NEEDED pages) ===" +echo "Critical (80-100): $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 80' | wc -l) pages" +echo "High (60-79): $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 60 && $2 < 80' | wc -l) pages" +echo "Medium (40-59): $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 40 && $2 < 60' | wc -l) pages" +echo "Low (0-39): $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 < 40' | wc -l) pages" + +# Clean up tracking files after categorisation +rm examples-docs.txt api-affected-docs.txt +``` + +**Risk Scoring System (0-100):** + +Pages requiring review are prioritised by risk score based on multiple factors: + +1. **Change Source (0-40 points)**: + + - API changes: +25 points (may require doc updates) + - Example changes: +25 points (code users copy must be correct) + - Both API and examples: +50 points (maximum source risk) + +2. **Change Magnitude (0-25 points)**: + + - > 200 lines: +25 points + - 100-200 lines: +20 points + - 50-100 lines: +15 points + - 20-50 lines: +10 points + - <20 lines: +5 points + +3. **Content Type (0-20 points)**: + + - New major sections (`## Heading`): +12 points + - New warnings/notes: +8 points + +4. **Page Importance (0-15 points)**: + - High priority (from **Priority Pages** ā†’ High priority): +15 points + - Medium priority (from **Priority Pages** ā†’ Medium priority): +10 points + - Test pages: -10 points (lower priority) + +**Risk Levels**: + +- **Critical (80-100)**: Review first - high impact/high risk changes +- **High (60-79)**: Review early - significant changes or important pages +- **Medium (40-59)**: Standard review - moderate impact +- **Low (0-39)**: Review when time permits - minor changes or less critical pages + +**Trivial Change Detection Strategy:** + +The filtering uses a **whitelist approach** with the following criteria: + +1. **Example/API Change Override**: Pages with modified examples or API references are **ALWAYS** marked for review (with appropriate risk score), regardless of their docs file changes. This is critical because: + + - Example changes may affect documentation accuracy even without docs file changes + - API changes may require documentation updates even if not yet applied + - These changes indicate functional updates that need validation + +2. **Whitespace-only changes**: For remaining pages, diff with `-w --ignore-blank-lines` to catch pure whitespace + +3. **Known trivial patterns**: ALL added lines must match one of: + + - Code block metadata: `format="snippet"` or `format="generated"` attributes + - Frontmatter changes: `enterprise:`, `title:` fields + - Structural wrapping: `{` or `}` for code snippet wrapping + - Empty lines + +4. **No substantive content**: Must not contain: + - New sections (`##` headings) + - New warnings or notes (`{% warning %}`, `{% note %}`) + - New prose content (sentences starting with capital letters) + +**Conservative Approach**: If **any** line doesn't match a known trivial pattern, the page is marked for review. This errs on the side of over-reviewing rather than missing substantive changes. + +**Test Page Pattern:** + +- Pages ending in `-test` with only additions (no deletions) +- These are new test documentation pages that don't affect main documentation + +### Step 7: Create Review Task Lists + +Generate two task lists using the paths from **Output Paths** in the product configuration: + +1. **Filtered list**: Only pages needing substantive review +2. **Complete list**: All modified pages (for reference) + +> **Note**: In the bash below, substitute `${FILTERED_LIST}` and `${COMPLETE_LIST}` with the filtered and complete task list paths from **Output Paths**. Substitute `${DOCS_PATH}` with the docs root from **Paths**. Substitute the `/docs-review` command references with the docs review command from **Product** configuration. + +**Create the filtered list:** + +```bash +cat > ${FILTERED_LIST} << EOF +# Release Documentation Review (Filtered) + +## Summary + +- Previous Release: ${PREVIOUS_BRANCH} +- Current Release: ${CURRENT_BRANCH} +- Total Pages Modified: $(wc -l < all-affected-docs.txt) +- Pages Requiring Review: $(grep -c '^REVIEW_NEEDED,' /tmp/categorized-docs.txt) +- Pages Skipped (Trivial): $(grep -c '^SKIP_TRIVIAL,' /tmp/categorized-docs.txt) +- Pages Skipped (Test): $(grep -c '^SKIP_TEST_NEW,' /tmp/categorized-docs.txt) + +## Risk Score Distribution + +Pages are prioritised by risk score (0-100) based on: +- Change source (examples/API changes) +- Change magnitude (lines changed) +- Content type (new sections, warnings) +- Page importance (from **Priority Pages** configuration) + +- **Critical (80-100)**: $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '\$2 >= 80' | wc -l) pages +- **High (60-79)**: $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '\$2 >= 60 && \$2 < 80' | wc -l) pages +- **Medium (40-59)**: $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '\$2 >= 40 && \$2 < 60' | wc -l) pages +- **Low (0-39)**: $(grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '\$2 < 40' | wc -l) pages + +## Skipped Pages + +### Trivial Formatting Changes +EOF + +grep '^SKIP_TRIVIAL,' /tmp/categorized-docs.txt | cut -d',' -f4 | while read page; do + echo "- ${page}" >> ${FILTERED_LIST} +done + +cat >> ${FILTERED_LIST} << 'EOF' + +### New Test Pages +EOF + +grep '^SKIP_TEST_NEW,' /tmp/categorized-docs.txt | cut -d',' -f4 | while read page; do + echo "- ${page}" >> ${FILTERED_LIST} +done + +cat >> ${FILTERED_LIST} << 'EOF' + +## Pages Requiring Review + +Review in order of risk score (highest priority first). + +### Critical Priority (Risk: 80-100) + +EOF + +# Add critical risk pages +grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 80' | while IFS=',' read category risk_score total_lines page; do + cat >> ${FILTERED_LIST} << ENDTASK +- [ ] **${page}** - Risk: ${risk_score} (${total_lines} lines) + - Command: \`/docs-review ${DOCS_PATH}/${page}/index.mdoc\` + +ENDTASK +done + +cat >> ${FILTERED_LIST} << 'EOF' + +### High Priority (Risk: 60-79) + +EOF + +# Add high risk pages +grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 60 && $2 < 80' | while IFS=',' read category risk_score total_lines page; do + cat >> ${FILTERED_LIST} << ENDTASK +- [ ] **${page}** - Risk: ${risk_score} (${total_lines} lines) + - Command: \`/docs-review ${DOCS_PATH}/${page}/index.mdoc\` + +ENDTASK +done + +cat >> ${FILTERED_LIST} << 'EOF' + +### Medium Priority (Risk: 40-59) + +EOF + +# Add medium risk pages +grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 >= 40 && $2 < 60' | while IFS=',' read category risk_score total_lines page; do + cat >> ${FILTERED_LIST} << ENDTASK +- [ ] **${page}** - Risk: ${risk_score} (${total_lines} lines) + - Command: \`/docs-review ${DOCS_PATH}/${page}/index.mdoc\` + +ENDTASK +done + +cat >> ${FILTERED_LIST} << 'EOF' + +### Low Priority (Risk: 0-39) + +EOF + +# Add low risk pages +grep '^REVIEW_NEEDED,' /tmp/categorized-docs.txt | awk -F',' '$2 < 40' | while IFS=',' read category risk_score total_lines page; do + cat >> ${FILTERED_LIST} << ENDTASK +- [ ] **${page}** - Risk: ${risk_score} (${total_lines} lines) + - Command: \`/docs-review ${DOCS_PATH}/${page}/index.mdoc\` + +ENDTASK +done +``` + +**Create the complete list** (for reference): + +```bash +# Create complete unfiltered task list (substitute COMPLETE_LIST and DOCS_PATH from product config) +cat all-affected-docs.txt | while read page; do + cat >> ${COMPLETE_LIST} << ENDTASK +- [ ] **${page}** + - Command: \`/docs-review ${DOCS_PATH}/${page}/index.mdoc\` + +ENDTASK +done +``` + +**Use the filtered list** for actual reviews unless there's reason to suspect the filtering missed something important. + +### Step 8: Execute Documentation Reviews + +**CRITICAL REQUIREMENTS:** + +1. **ONE PAGE PER SUB-AGENT - NO BATCHING** +2. **MUST USE SlashCommand TOOL - NO CUSTOM IMPLEMENTATIONS** + +#### Execution Pattern + +For each documentation page in the **filtered task list**, spawn a dedicated sub-agent that: + +1. **Reviews exactly ONE page** (no batching allowed) +2. **Uses the SlashCommand tool** to invoke the docs review command from **Product** configuration +3. **Validates the review outputs** (files specified in **Verification Paths**) + +#### Sub-Agent Prompt Template + +Each sub-agent must receive this strict prompt (substitute product-specific values): + +``` +You are reviewing the [PAGE_NAME] documentation page for [PRODUCT_NAME] release from [PREVIOUS_BRANCH] to [CURRENT_BRANCH]. + +STRICT REQUIREMENTS: + +1. MANDATORY: Use SlashCommand tool to invoke the docs review command + - Execute: SlashCommand with command "/docs-review [DOCS_PATH]/[PAGE_NAME]/index.mdoc" + - DO NOT create custom review implementations + - DO NOT perform manual reviews + - DO NOT skip the SlashCommand tool + +2. Single Page Only + - Review ONLY: [PAGE_NAME] + - DO NOT review multiple pages + - DO NOT batch reviews + +3. Verify Outputs + - After the review completes, confirm the verification files exist + - If files are missing, report failure + +4. Return Summary + - Report review status (PASSED / ISSUES FOUND / FAILED) + - List critical issues if any found + - Confirm SlashCommand was used + +Execute the review now. +``` + +#### Parallel Execution Strategy + +Launch all sub-agents in parallel for maximum efficiency: + +1. **Read the filtered task list** to get all pages requiring review +2. **Create one Task per page** in a single message (multiple tool calls) +3. **Monitor completion** of all agents +4. **Validate outputs** from each agent + +#### Implementation Example + +```bash +# Read filtered task list (substitute the filtered task list path from Output Paths) +PAGES=$(grep "^- \[ \]" ${FILTERED_LIST} | \ + grep -oP '\*\*\K[^*]+' | head -10) + +# For each page, spawn a dedicated agent +# (In practice, you'll use multiple Task tool calls in one message) +``` + +#### Validation After Execution + +After all agents complete, verify: + +1. Each agent used SlashCommand tool (check agent outputs) +2. Each page has the review files specified in **Verification Paths** +3. No agent reviewed multiple pages (batching violation) + +**If validation fails:** + +- Identify which pages were not properly reviewed +- Identify which agents didn't use SlashCommand +- Re-launch failed agents with corrected strict prompts + +#### Handling Large Page Counts + +For releases with many pages (e.g., 50+): + +1. **Launch in waves** if needed (e.g., 20 agents at a time) +2. **Prioritise by risk score** (Critical ā†’ High ā†’ Medium ā†’ Low) +3. **Monitor token usage** across agents +4. **Wait for wave completion** before launching next wave + +**Note**: Use the filtered list by default. Only review skipped pages if: + +- You find issues in related pages that suggest skipped pages may be affected +- The release is high-risk and requires maximum thoroughness +- Stakeholders specifically request full coverage + +### Step 9: Generate Summary Report + +After all individual page reviews are complete: + +1. **Aggregate findings** from all technical review reports +2. **Identify patterns** across multiple pages +3. **Prioritise issues** by severity and frequency +4. **Generate release readiness assessment** + +Write the final summary to the summary path from **Output Paths** in the product configuration. + +## Output Format + +### Filtered Task List (Primary Output) + +Write to the filtered task list path from **Output Paths**. + +This is the **primary list to use for reviews**. It excludes trivial formatting changes and focuses on substantive updates. + +Format: + +```markdown +# Release Documentation Review (Filtered) + +## Summary + +- Previous Release: ${PREVIOUS_BRANCH} +- Current Release: ${CURRENT_BRANCH} +- Total Pages Modified: ${TOTAL_MODIFIED} +- Pages Requiring Review: ${REVIEW_NEEDED_COUNT} +- Pages Skipped (Trivial): ${SKIP_TRIVIAL_COUNT} +- Pages Skipped (Test): ${SKIP_TEST_COUNT} + +## Risk Score Distribution + +Pages are prioritised by risk score (0-100) based on: +- Change source (examples/API changes) +- Change magnitude (lines changed) +- Content type (new sections, warnings) +- Page importance (from **Priority Pages** configuration) + +- **Critical (80-100)**: ${CRITICAL_COUNT} pages +- **High (60-79)**: ${HIGH_COUNT} pages +- **Medium (40-59)**: ${MEDIUM_COUNT} pages +- **Low (0-39)**: ${LOW_COUNT} pages + +## Analysis Summary + +After analysing all modified documentation pages, categorised by change type. + +### Skipped: Trivial Formatting Changes + +These pages only have code formatting standardisation: + +- page-1 +- page-2 + +### Skipped: New Test Pages + +New test documentation pages (all additions): + +- test-page-1 +- test-page-2 + +### Pages Requiring Review + +- [ ] **page-name**: /docs-review command... +``` + +### Complete Task List (Reference) + +Write to the complete task list path from **Output Paths**. + +This list includes **all** modified pages without filtering. Use for reference or when maximum thoroughness is required. + +Format: + +```markdown +# Release Documentation Review Tasks (Complete) + +## Summary + +- Previous Release: ${PREVIOUS_BRANCH} +- Current Release: ${CURRENT_BRANCH} +- Total Pages Modified: ${TOTAL_PAGES} +- Direct Doc Changes: ${DIRECT_COUNT} +- Example Changes: ${EXAMPLE_COUNT} +- API Impact: ${API_COUNT} + +## All Modified Pages + +- [ ] page-1: /docs-review command... +- [ ] page-2: /docs-review command... +``` + +### Final Summary Report + +Write to the summary path from **Output Paths**. + +Format: + +```markdown +# Release Documentation Review Summary + +## Executive Summary + +[Brief overview of documentation status for release] + +## Review Statistics + +- Total Pages Reviewed: X +- Pages with Issues: Y +- Critical Issues: Z +- Estimated Fix Time: N hours + +## Critical Issues Requiring Immediate Fix + +[List of blocking documentation issues] + +## Pattern Analysis + +[Common issues found across multiple pages] + +## Recommendations + +[Prioritised list of documentation updates needed] + +## Release Risk Assessment + +[Overall documentation readiness: Low/Medium/High] +``` + +## Important Considerations + +1. **Filtering and Triage**: + + - **Use the filtered list by default** - it uses risk scoring + conservative whitelist approach + - **Risk scores (0-100) prioritise review order**: Critical (80-100) ā†’ High (60-79) ā†’ Medium (40-59) ā†’ Low (0-39) + - **Example/API changes override all filtering**: Pages with modified examples or API references are ALWAYS reviewed, even if docs file changes are trivial or absent + - **Whitespace-only changes** are automatically detected with `git diff -w` + - **Trivial patterns** are explicitly whitelisted (code block metadata, frontmatter, structural wrapping) + - **Conservative by design**: Any line that doesn't match a known trivial pattern ā†’ mark for review + - New test pages (ending in `-test` with only additions) are skipped by default + - If filtering reduces review load by >20%, mention this efficiency gain in reports + - Review skipped pages only if issues found in related pages suggest impact + +2. **Change Impact Analysis with Risk Scoring**: + + - **Change source** (40 points max): Example/API changes score highest + - **Change magnitude** (25 points max): Larger changes = higher risk + - **Content type** (20 points max): New sections/warnings increase risk + - **Page importance** (15 points max): Pages listed in **Priority Pages** score highest + - **Combined scores** guide review order - tackle high-risk pages first + - Pages with >100 lines changed likely have major feature updates + +3. **Review Scope Management**: + + - For large releases (>50 pages after filtering), use wave-based parallelism (launch multiple single-page sub-agents concurrently) rather than batching + - Prioritise based on user-facing importance (getting started, key features, upgrade guides) + - Start with largest changes first (they often reveal patterns) + - Skip generated or auto-updated sections if identified + +4. **Quality Gates**: + - All HIGH priority issues must be resolved before release + - MEDIUM priority issues should be documented in release notes + - LOW priority issues can be addressed post-release + - Formatting-only changes don't block releases + +## Execution Tips + +### Mandatory Practices + +- **Always run the filtering step (Step 6)** before creating task lists - it typically saves 20-40% of review effort +- **ONE PAGE PER SUB-AGENT** - Never batch multiple pages into a single agent +- **USE SlashCommand TOOL** - Always invoke the docs review command via SlashCommand, never create custom review implementations +- **Validate outputs** - After reviews, confirm plan and report files exist at standard locations + +### Performance Optimisation + +- **Launch agents in parallel** - Use single message with multiple Task tool calls for maximum efficiency +- **Batch API calls, not reviews** - Launch 10-20 agents concurrently, but each reviews only ONE page +- **Monitor completion** - Track which agents finish and which pages remain +- **Cache git operations** - Store diff results in `/tmp/diff-stats.txt` and `/tmp/categorized-docs.txt` + +### Quality Assurance + +- **Verify SlashCommand usage** - Check agent outputs confirm they used SlashCommand tool +- **Validate standard outputs** - Ensure review plan and report files are in correct locations +- **Check for batching violations** - Confirm no agent reviewed multiple pages +- **Example validation** - If Step 3 found example changes, verify examples run correctly before reviewing docs + +### Progress Tracking + +- **Provide status updates** - Report completion progress for long-running reviews (e.g., "35/77 pages reviewed") +- **Identify failures early** - If agents don't use SlashCommand or output goes to wrong location, stop and fix +- **Wave-based execution** - For 50+ pages, review in waves of 15-20 agents each + +## Benefits of Filtering + +Typical filtering results across releases: + +- **Trivial formatting changes**: 5-10% of modified pages (pure formatting standardisation) +- **New test pages**: 10-15% of modified pages (test documentation that doesn't affect main docs) +- **Total efficiency gain**: 20-30% reduction in review workload while maintaining quality + +Remember: This comprehensive review with intelligent filtering ensures documentation quality matches code quality for the release while optimising reviewer time. diff --git a/external/ag-shared/prompts/commands/git/branch-save-context.md b/external/ag-shared/prompts/commands/git/branch-save-context.md deleted file mode 100644 index b30f823f397..00000000000 --- a/external/ag-shared/prompts/commands/git/branch-save-context.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -targets: ['*'] -description: 'Save/update branch-specific context to .context/ directory (branch memory)' ---- - -# Branch Save Context - -Save or update context for the current branch. Keep it concise - only preserve information useful for future sessions. - -## Usage - -`/branch-save-context` - -No arguments required - automatically detects current branch. - -## Workflow - -### STEP 1: Determine Context File Path - -```bash -# Get current branch name -BRANCH=$(git branch --show-current) - -# Get main repo root (works from worktrees) -MAIN_REPO=$(git rev-parse --path-format=absolute --git-common-dir | sed 's/\\.git$//') - -# Derive slug with hash suffix to avoid collisions (e.g. feature/foo vs feature-foo) -SLUG_BASE=$(echo "$BRANCH" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//') -HASH=$(echo -n "$BRANCH" | shasum | cut -c1-6) -SLUG="${SLUG_BASE}-${HASH}" - -# Context file path -CONTEXT_FILE="${MAIN_REPO}.context/${SLUG}.md" - -# Ensure directory exists -mkdir -p "${MAIN_REPO}.context" -``` - -### STEP 2: Check for Existing Context - -If the context file already exists, read its current contents. When updating, **prune resolved items and transient issues**. - -### STEP 3: Gather Context Information - -Ask the user what to save. Keep responses brief. - -**For new context**: What's the branch intent? Any patterns worth remembering? - -**For updates**: What changed? Any gaps resolved? New patterns discovered? - -### STEP 4: Write Context File - -Use this minimal template: - -```markdown ---- -branch: {branch-name} -updated: {ISO-date} ---- - -# {branch-name} - -## Intent - -{1-2 sentences: what this branch accomplishes} - -## Patterns - -{Only include if there are reusable code patterns} - -## Gaps - -{Only persistent gaps - architectural decisions, known limitations} - -## References - -{Links to ticket, relevant docs} -``` - -### STEP 5: Confirm Save - -``` -Saved: {context-file-path} -``` - -## What to Keep vs Prune - -### KEEP (future-relevant) - -- High-level intent (stable goal of the branch) -- Reusable patterns (code you'll copy again) -- Persistent gaps (architectural decisions pending, known limitations) -- Reference links (ticket, design docs) - -### PRUNE (transient) - -- Temporary test failures -- Build/environment issues -- Implementation gaps now resolved -- Debugging notes and scratch work -- Session-specific troubleshooting -- Resolved gaps (remove the checkbox, just delete) - -## Principles - -- **Brevity over completeness** - if in doubt, leave it out -- **Future self test** - will this help in a new session next week? -- **No resolved items** - once fixed, remove it entirely -- **Patterns must be reusable** - don't document one-off code diff --git a/external/ag-shared/prompts/commands/plan/review.md b/external/ag-shared/prompts/commands/plan/review.md index ccface46ca2..8bd1cf2ed67 100644 --- a/external/ag-shared/prompts/commands/plan/review.md +++ b/external/ag-shared/prompts/commands/plan/review.md @@ -5,7 +5,7 @@ description: 'Review plans for completeness, correctness, and verifiability' # Plan Review Prompt -You are a plan reviewer for AG Charts. Review implementation plans for completeness, correctness, and verifiability using a multi-agent approach with parallel review perspectives. +You are a plan reviewer. Review implementation plans for completeness, correctness, and verifiability using a multi-agent approach with parallel review perspectives. ## Input Requirements diff --git a/external/ag-shared/prompts/commands/pr/split.md b/external/ag-shared/prompts/commands/pr/split.md index 4fbe9a7c0e1..ad190bbb277 100644 --- a/external/ag-shared/prompts/commands/pr/split.md +++ b/external/ag-shared/prompts/commands/pr/split.md @@ -42,8 +42,17 @@ Verify the working tree is clean, not on main branch, and gh CLI is authenticate Determine the commit message prefix from the branch name: -1. If branch matches `ag-NNNNN/description` pattern: extract JIRA ticket (e.g., `AG-12345`) -2. Otherwise: derive prefix from branch name (e.g., `feature/null-keys` becomes `null-keys`) +1. Detect the project from the repo name (enclosing directory): + + | Repo | Branch Pattern | JIRA Prefix | + |---------------|---------------------------|-------------| + | `ag-studio` | `st-NNNNN/description` | `ST-` | + | `ag-charts` | `ag-NNNNN/description` | `AG-` | + | `ag-grid` | `ag-NNNNN/description` | `AG-` | + | *(default)* | `ag-NNNNN/description` | `AG-` | + +2. If branch matches the project's pattern: extract JIRA ticket (e.g., `ST-12345`, `AG-12345`) +3. Otherwise: derive prefix from branch name (e.g., `feature/null-keys` becomes `null-keys`) Store this prefix for use in commit messages and PR titles. @@ -208,9 +217,8 @@ This phase is essential. Each PR must be polished until reviewer-ready, not just - Would the PR title make sense in a changelog? 5. **Run Build Validation** - - Type checking: `yarn nx build:types ` - - Linting: `yarn nx lint ` - - Tests: `yarn nx test ` + - Run the project's pre-commit validation commands against each affected package + - Ensure type checking, linting, and tests all pass before proceeding 6. **Fix Issues** - Code quality issues: fix and amend or add fixup commits @@ -265,7 +273,7 @@ PR N of M in the series. ## JIRA -Jira: [AG-12345](https://ag-grid.atlassian.net/browse/AG-12345) +Jira: [TICKET-12345](https://jira.example.com/browse/TICKET-12345) ## Test Plan diff --git a/external/ag-shared/prompts/commands/git/branch-load-context.md b/external/ag-shared/prompts/commands/recall.md similarity index 51% rename from external/ag-shared/prompts/commands/git/branch-load-context.md rename to external/ag-shared/prompts/commands/recall.md index 29766edfdca..8150e47f2c1 100644 --- a/external/ag-shared/prompts/commands/git/branch-load-context.md +++ b/external/ag-shared/prompts/commands/recall.md @@ -1,28 +1,24 @@ --- targets: ['*'] -description: 'Load branch-specific context from .context/ directory (branch memory)' +description: 'Load branch context and browse project memory for session resumption' --- -# Branch Load Context +# Recall -Load saved context for the current branch to resume work with full awareness of intent, patterns, and known gaps. +## Usage ā€” `/recall` -## Usage +Load branch-scoped context from `.context/` and optionally browse project-scoped memory in `.rulesync/`. -`/branch-load-context` +## STEP 1: Load Branch Memory -No arguments required - automatically detects current branch. - -## Workflow - -### STEP 1: Determine Context File Path +### Determine Context File Path ```bash # Get current branch name BRANCH=$(git branch --show-current) # Get main repo root (works from worktrees) -MAIN_REPO=$(git rev-parse --path-format=absolute --git-common-dir | sed 's/\\.git$//') +MAIN_REPO=$(git rev-parse --path-format=absolute --git-common-dir | sed 's/\.git$//') # Derive slug with hash suffix to avoid collisions (e.g. feature/foo vs feature-foo) SLUG_BASE=$(echo "$BRANCH" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//') @@ -33,7 +29,7 @@ SLUG="${SLUG_BASE}-${HASH}" CONTEXT_FILE="${MAIN_REPO}.context/${SLUG}.md" ``` -### STEP 2: Load Context +### Load and Present Check if the context file exists: @@ -45,24 +41,7 @@ else fi ``` -### STEP 3: Present Context - -If the context file exists, read and present its contents to provide awareness of: - -- **Intent**: What this branch is trying to accomplish -- **Key Patterns**: Code snippets and approaches used in this branch -- **Known Gaps**: Outstanding issues or areas needing attention -- **References**: Relevant commands, docs, tickets, or websites - -If no context file exists, inform the user: - -> No saved context found for branch `{branch}`. -> -> Run `/branch-save-context` to create context for this branch. - -## Output Format - -When context is found, present a summary: +**If found**, read and present its contents: ```markdown ## Branch Context Loaded: {branch} @@ -80,8 +59,28 @@ When context is found, present a summary: {Full context file contents} ``` +**If not found**, inform the user: + +> No saved context found for branch `{branch}`. +> +> Run `/remember` and choose **Branch** to create context for this branch. + +## STEP 2: Project Memory Summary (optional) + +After presenting branch context, offer to show project memory: + +> Project rules and learnings in `.rulesync/rules/` load automatically based on file-pattern globs. +> Want to browse the project memory files? + +If the user says yes: + +1. List `.rulesync/rules/` files with a one-line description of each +2. User can request to read specific memory files for details +3. This is informational ā€” project rules auto-load during normal work via globs + ## Notes - Context files are stored in the main repo root, shared across all worktrees - Context persists even when worktrees are deleted -- Files are gitignored - this is personal/local context, not shared +- Branch context files are gitignored ā€” this is personal/local context, not shared +- Project memory (`.rulesync/rules/`) is committed and shared with the team diff --git a/external/ag-shared/prompts/commands/remember.md b/external/ag-shared/prompts/commands/remember.md new file mode 100644 index 00000000000..2c27e71abe4 --- /dev/null +++ b/external/ag-shared/prompts/commands/remember.md @@ -0,0 +1,216 @@ +--- +targets: ['*'] +description: 'Save branch context or project learnings as agentic memory' +--- + +# Remember + +## Usage ā€” `/remember` + +Save branch-scoped context (`.context/`) or project-scoped learnings (`.rulesync/`). + +## STEP 1: Choose Memory Type + +Ask the user: + +**What would you like to remember?** + +1. **Branch** ā€” save context for this branch (intent, patterns, gaps) +2. **Project** ā€” extract learnings from this conversation into rules/skills +3. **Both** ā€” do branch first, then project + +Use AskUserQuestion. Then follow the corresponding path(s) below. + +--- + +## Branch Memory Path + +Save or update context for the current branch. Keep it concise ā€” only preserve information useful for future sessions. + +### STEP B1: Determine Context File Path + +```bash +# Get current branch name +BRANCH=$(git branch --show-current) + +# Get main repo root (works from worktrees) +MAIN_REPO=$(git rev-parse --path-format=absolute --git-common-dir | sed 's/\.git$//') + +# Derive slug with hash suffix to avoid collisions (e.g. feature/foo vs feature-foo) +SLUG_BASE=$(echo "$BRANCH" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//') +HASH=$(echo -n "$BRANCH" | shasum | cut -c1-6) +SLUG="${SLUG_BASE}-${HASH}" + +# Context file path +CONTEXT_FILE="${MAIN_REPO}.context/${SLUG}.md" + +# Ensure directory exists +mkdir -p "${MAIN_REPO}.context" +``` + +### STEP B2: Check for Existing Context + +If the context file already exists, read its current contents. When updating, **prune resolved items and transient issues**. + +### STEP B3: Gather Context Information + +Ask the user what to save. Keep responses brief. + +**For new context**: What's the branch intent? Any patterns worth remembering? + +**For updates**: What changed? Any gaps resolved? New patterns discovered? + +### STEP B4: Write Context File + +Use this minimal template: + +```markdown +--- +branch: {branch-name} +updated: {ISO-date} +--- + +# {branch-name} + +## Intent + +{1-2 sentences: what this branch accomplishes} + +## Patterns + +{Only include if there are reusable code patterns} + +## Gaps + +{Only persistent gaps ā€” architectural decisions, known limitations} + +## References + +{Links to ticket, relevant docs} +``` + +### STEP B5: Confirm Save + +``` +Saved: {context-file-path} +``` + +### What to Keep vs Prune + +**KEEP** (future-relevant): + +- High-level intent (stable goal of the branch) +- Reusable patterns (code you'll copy again) +- Persistent gaps (architectural decisions pending, known limitations) +- Reference links (ticket, design docs) + +**PRUNE** (transient): + +- Temporary test failures +- Build/environment issues +- Implementation gaps now resolved +- Debugging notes and scratch work +- Session-specific troubleshooting +- Resolved gaps (remove the checkbox, just delete) + +### Principles + +- **Brevity over completeness** ā€” if in doubt, leave it out +- **Future self test** ā€” will this help in a new session next week? +- **No resolved items** ā€” once fixed, remove it entirely +- **Patterns must be reusable** ā€” don't document one-off code + +--- + +## Project Memory Path + +Extract decisions, patterns, and learnings from the current conversation and persist them as agentic memory. + +### When to Use + +- After resolving a non-obvious issue with a specific approach +- When discovering a pattern that should be reused +- When user corrects agent behaviour or preferences +- After clarifying how existing rules should be interpreted + +### STEP P1: Memory Extraction + +Review the conversation to identify: + +1. **Decisions** ā€” Specific choices made (e.g., "use X approach instead of Y") +2. **Corrections** ā€” Mistakes caught and how to avoid them +3. **Patterns** ā€” Reusable approaches that worked well +4. **Preferences** ā€” User/project preferences revealed +5. **Clarifications** ā€” Ambiguous rules made concrete + +For each candidate, extract: +- The core learning (1-2 sentences) +- Context where it applies +- Why it matters + +### STEP P2: Classification + +Determine the best location for each memory: + +| Type | Location | When | +|------|----------|------| +| Domain rule | `.rulesync/rules/{domain}.md` | Topic-specific guidance | +| Command enhancement | `.rulesync/commands/{cmd}.md` | Workflow-specific | +| Skill update | `external/prompts/skills/{skill}/` | Skill-scoped learning | +| New rule file | `.rulesync/rules/{new}.md` | Distinct topic, 3+ guidelines | + +**Constraints**: +- **Never update root files directly** ā€” `CLAUDE.md`, `AGENTS.md`, and files with `root: true` frontmatter are managed separately. If a memory belongs there, recommend creating/updating a non-root rule that gets referenced instead. +- **Prefer existing files** ā€” only create new files when the topic is clearly distinct and has sufficient content. + +### STEP P3: Interactive Presentation + +For each memory candidate, present to user: + +#### Memory N of M + +**Learning**: [The extracted insight] + +**Recommended location**: `path/to/file.md` ā†’ Section Name + +**Options**: +1. Add to recommended location +2. Add to different location (specify) +3. Rephrase the learning +4. Skip this memory + +Use AskUserQuestion with these options. Wait for user response before proceeding. + +### STEP P4: Execution + +For approved memories: + +1. **Read** the target file to understand current structure +2. **Locate** the appropriate section (or create if needed) +3. **Format** the memory to match file conventions: + - Rules: Use `-` bullet points, match existing tone + - Commands: Integrate into relevant phase/section +4. **Write** the update using Edit tool +5. **Confirm** the change to user + +### STEP P5: Output + +After processing all memories, summarise: + +``` +## Memory Update Summary + +Added: N memories +Skipped: M memories +Files modified: +- path/to/file1.md (section updated) +- path/to/file2.md (new section added) +``` + +### Project Memory Constraints + +- **Never update root files** ā€” Do not modify `CLAUDE.md`, `AGENTS.md`, or any file with `root: true` in frontmatter. These are managed separately. Instead, create or update a non-root rule file that can be referenced. +- Keep memories atomic ā€” one concept per update +- Match the writing style of the target file +- If unsure about location, ask user rather than guess +- Memories should be actionable, not just observations diff --git a/external/ag-shared/prompts/guides/code-quality.md b/external/ag-shared/prompts/guides/code-quality.md index 9839bc1fdb1..c414c895f16 100644 --- a/external/ag-shared/prompts/guides/code-quality.md +++ b/external/ag-shared/prompts/guides/code-quality.md @@ -44,13 +44,3 @@ This guide covers code quality practices, including avoiding code bloat, comment - For test changes, verify completeness by comparing with related tests in the same file - Ensure naming clearly conveys intent (especially for boolean/flag variables) -## Essential Quality Commands - -- `yarn nx format` ā€“ format repo files; run from the project root before committing -- `yarn nx build:types ` ā€“ regenerate declaration files when touching exported APIs -- `yarn nx lint ` ā€“ apply ESLint and custom rules before final review - -## Formatting Best Practice - -- Make sure to run `yarn nx format` on any changes to ensure consistent formatting before commit -- Prefer running `yarn nx format` in the root of the repo to format changes, as there are config nuances that aren't taken into account when directly running tooling in more specific places diff --git a/external/ag-shared/prompts/guides/docs-review-integration.md b/external/ag-shared/prompts/guides/docs-review-integration.md new file mode 100644 index 00000000000..70a71a91b18 --- /dev/null +++ b/external/ag-shared/prompts/guides/docs-review-integration.md @@ -0,0 +1,238 @@ +# Docs Review Integration Guide + +This guide covers how to integrate the shared docs review methodology into any AG product repo (ag-grid, ag-studio, etc.). + +## Architecture + +The shared docs review uses an **inverted reference pattern** (same as PR reviews): + +- **Core files** (`external/ag-shared/prompts/commands/docs/_docs-review-core.md` and `_release-docs-review-core.md`): Generic workflow methodology, report structure, quality standards +- **Thin wrappers** (plain files in each repo's `.rulesync/commands/`): Product configuration block + single reference line to the core + +The LLM reads the product configuration first, then follows the core methodology, substituting product values at runtime. No build-time templating required. + +## Prerequisites + +- The repo already uses `external/ag-shared/` as a git subrepo +- The repo already uses rulesync and the `setup-prompts.sh` pipeline +- No private prompts repo is required ā€” all product-specific files are plain files in `.rulesync/` + +## Step 1: Pull the Latest ag-shared + +```bash +git subrepo pull external/ag-shared +``` + +This brings in the core files: + +- `external/ag-shared/prompts/commands/docs/_docs-review-core.md` +- `external/ag-shared/prompts/commands/docs/_release-docs-review-core.md` + +## Step 2: Create the Product Configuration Wrapper for `/docs-review` + +Create `.rulesync/commands/docs-review.md` as a plain file. Sections marked with a "Required" note must be present ā€” the core methodology references these by exact name. + +```markdown +--- +targets: ['*'] +description: 'Review documentation pages for technical accuracy and example consistency' +--- + +# Documentation Review - [Product Name] + +You are a technical documentation reviewer for [Product Name]. + +## Product Configuration + +### Input Requirements +> Required ā€” referenced by exact name in the core methodology. + +User provides: +- Documentation page path: `[path to docs]/${pageName}/index.mdoc` +- Live dev URL: `[dev server URL]/${pageName}/` + +### Orchestration Indicator +- Orchestrator script: `[path to orchestrator, if any]` + +### File Resolution Rules +> Required ā€” referenced by exact name in the core methodology. + +Map documentation references to TypeScript definition files: + +| If docs mention | Then check file | +| ------------------------- | ---------------------------------------- | +| [Pattern for your product] | [Path to types package] | +| Interface name like `XxxOptions` | Search `[types path]/**/*` | +| Generic config property | `[path to main options file]` | + +### Implementation Resolution Rules +> Required ā€” referenced by exact name in the core methodology. + +Map features to source implementation files: + +| Feature Category | Implementation Path Pattern | +| ---------------- | --------------------------- | +| [Your feature categories] | [Your source paths] | + +### Example Path Pattern +> Required ā€” referenced by exact name in the core methodology. + +`[docs path]/${pageName}/_examples/${exampleName}/` +- Required: `main.ts` +- Optional: `data.ts`, `styles.css` + +### Exceptions File Path +`[docs path]/${pageName}/technical-review-exceptions.md` + +### Output Paths +> Required ā€” referenced by exact name in the core methodology. + +- Review plans: `[plans path]/${pageName}.md` +- Reports: `[docs path]/${pageName}/reports/technical-review-report.md` +- Summary: `reports/docs-review/summary.md` + +### Default Value Verification Hierarchy +> Required ā€” referenced by exact name in the core methodology. +> Describe how default values are resolved in your product's architecture. +> For AG Charts this is: Module theme template -> @Property decorator -> TypeScript comments +> For AG Grid this might be: ColDef defaults -> GridOptions defaults -> etc. + +### Product-Specific Conventions +- [List any API conventions specific to your product] +- [Known accepted patterns that should NOT be flagged] + +## Review Methodology + +**Read and follow all instructions in `external/ag-shared/prompts/commands/docs/_docs-review-core.md` for the review process, applying the product configuration above.** +``` + +## Step 3: Create the Product Configuration Wrapper for `/release-docs-review` + +Create `.rulesync/commands/release-docs-review.md` as a plain file: + +```markdown +--- +targets: ['*'] +description: 'Review all documentation changes between releases for accuracy and completeness' +--- + +# Release Documentation Review - [Product Name] + +You are an expert documentation reviewer for [Product Name], specialising in +release documentation validation. + +## Product Configuration + +### Product +> Required ā€” referenced by exact name in the core methodology. + +- Name: [Product Name] +- Docs review command: `/docs-review` + +### Paths +> Required ā€” referenced by exact name in the core methodology. +- Docs root: `[path to docs content]` +- Types root: `[path to public types package]` +- Docs file pattern: `[docs root]/**/*.mdoc` +- Examples pattern: `[docs root]/**/_examples/` +- Types file pattern: `[types root]/**/*.ts` + +### Release Branch Pattern +> Required ā€” referenced by exact name in the core methodology. + +- Format: `[your branch naming pattern, e.g. origin/bX.Y.Z]` +- Discovery command: `[shell command to list recent release branches]` + +### Priority Pages +> Required ā€” referenced by exact name in the core methodology. + +**High priority** (getting started, key features, upgrade guides): +`[comma-separated list of high-priority page names]` + +**Medium priority** (core features): +`[comma-separated list of medium-priority page names]` + +### Output Paths +> Required ā€” referenced by exact name in the core methodology. + +- Reports directory: `reports/` +- Filtered task list: `reports/release-docs-review-${PREVIOUS}-${CURRENT}-filtered.md` +- Complete task list: `reports/release-docs-review-${PREVIOUS}-${CURRENT}-tasks.md` +- Summary: `reports/release-docs-review-${PREVIOUS}-${CURRENT}-summary.md` + +### Verification Paths +After each page review, confirm these files exist: +- `[plans path]/${pageName}.md` +- `[docs path]/${pageName}/reports/technical-review-report.md` + +## Review Methodology + +**Read and follow all instructions in `external/ag-shared/prompts/commands/docs/_release-docs-review-core.md` for the review process, applying the product configuration above.** +``` + +## Step 4: Create Product-Specific Documentation Rules + +The shared core handles the review workflow, but each product needs rules describing its documentation conventions. Create these in `.rulesync/rules/` (or `external/prompts/guides/`). + +**Recommended supporting rules:** + +These files are not referenced by the review core but provide context that improves review quality. + +- **`docs-pages.md`** ā€” comprehensive guide to your documentation system: page types and standard structures, Markdoc/MDX component reference, content patterns, example integration conventions +- **`docs-checklist.md`** ā€” pre-submission quality checklist: content structure requirements, technical accuracy checks, example validation commands, framework compatibility checks + +**Optional:** + +- **`playbook-docs.md`** ā€” quick-reference workflow for docs changes +- **`example-tester.md`** (sub-agent in `.rulesync/subagents/`) ā€” if you want Full Mode interactive review (build, test, and validate examples). Without this, `/docs-review` operates in Adaptive/Degraded mode (static analysis only), which is still useful. + +Use an existing product's versions as a reference for structure and level of detail. + +## Step 5: Verify File Placement + +Confirm the files are in the correct locations (all plain files, no symlinks needed): + +``` +.rulesync/ +ā”œā”€ā”€ commands/ +ā”‚ ā”œā”€ā”€ docs-review.md ā† plain file (Step 2) +ā”‚ ā””ā”€ā”€ release-docs-review.md ā† plain file (Step 3) +ā””ā”€ā”€ rules/ + ā”œā”€ā”€ docs-pages.md ā† plain file (Step 4) + ā””ā”€ā”€ docs-checklist.md ā† plain file (Step 4) +``` + +## Step 6: Regenerate Tool Config + +```bash +./external/ag-shared/scripts/setup-prompts/setup-prompts.sh +``` + +Verify the commands appear in `.claude/commands/`: + +```bash +ls -la .claude/commands/docs-review.md .claude/commands/release-docs-review.md +``` + +## Step 7: Test + +1. Run `/docs-review [path-to-a-docs-page]` and confirm the LLM reads both your wrapper and the core +2. Check that the report references your product's file paths (not another product's paths) +3. Run `/release-docs-review` with two release branches and confirm page discovery works with your paths + +## Adoption Checklist + +- [ ] `git subrepo pull external/ag-shared` completed +- [ ] `.rulesync/commands/docs-review.md` created as plain file with all REQUIRED sections +- [ ] `.rulesync/commands/release-docs-review.md` created as plain file with all REQUIRED sections +- [ ] `.rulesync/rules/docs-pages.md` created (or equivalent) +- [ ] `.rulesync/rules/docs-checklist.md` created (or equivalent) +- [ ] `setup-prompts.sh` run successfully +- [ ] `/docs-review` tested on a real page +- [ ] `/release-docs-review` tested between two branches + +## Notes + +- **Batch orchestration**: The core methodology covers single-page and release-diff reviews. Batch orchestration across all pages is product-specific. Start with manual page-by-page invocation. +- **Estimated adoption effort**: ~2-3 hours per repo. +- **Section names are normative**: The core references wrapper sections by exact name. Renaming sections in either wrapper or core silently breaks cross-referencing. diff --git a/external/ag-shared/prompts/guides/nx-conventions.md b/external/ag-shared/prompts/guides/nx-conventions.md new file mode 100644 index 00000000000..379c709bc5d --- /dev/null +++ b/external/ag-shared/prompts/guides/nx-conventions.md @@ -0,0 +1,29 @@ +--- +targets: ['*'] +description: 'Nx project configuration conventions' +globs: ['**/project.json', 'nx.json'] +--- + +# Nx Conventions + +## Project Configuration + +- In `project.json` files, use `{projectRoot}` to reference paths relative to the project root. Do **not** prefix with `./` ā€” Nx interpolates `{projectRoot}` as a complete relative path from the workspace root (e.g. `tools/ssr-example`), so `{projectRoot}/script.sh` is correct while `./{projectRoot}/script.sh` is invalid. +- To prevent Nx from inferring targets from npm scripts in a `package.json`-only project, set `"nx": {"includedScripts": []}` in the package.json. An empty array suppresses all inferred script targets while keeping the project visible to Nx for dependency tracking. + +## The Synthetic "all" Project + +Each monorepo has a synthetic project named `all` (typically at `utilities/all/project.json`) that acts as an aggregate orchestrator for monorepo-wide operations. + +**How it works:** + +- Targets use the `nx:noop` executor with `dependsOn: ["^"]` to cascade operations across all packages without doing any work itself. +- It lists every publishable package in its `implicitDependencies` array, so running a target on `all` triggers that target on every listed package. +- It is set as the `defaultProject` in `nx.json`, so bare commands like `nx run build` or `nx run test` run against `all` and therefore cascade to all packages. + +**Key guidance:** + +- Do **not** treat `all` as a real, buildable project ā€” it has no meaningful source code. +- Do **not** add source files to it or attempt to import from it. +- Do **not** watch it for changes or add it to file-watcher configurations. +- When you need to run a target for a **specific** package, always specify the project explicitly (e.g. `nx run ag-studio:build`) rather than relying on the default project. diff --git a/external/ag-shared/prompts/guides/setup-prompts.md b/external/ag-shared/prompts/guides/setup-prompts.md index 63d69a033f3..21230659ba9 100644 --- a/external/ag-shared/prompts/guides/setup-prompts.md +++ b/external/ag-shared/prompts/guides/setup-prompts.md @@ -70,3 +70,15 @@ npx patch-package rulesync ``` This updates `patches/rulesync+*.patch` (which symlinks to `external/ag-shared/prompts/patches/`). + +## Shared Prompt Conventions + +When using the inverted reference pattern (shared core + thin wrapper), follow these rules to avoid silent breakage. + +### Section names are normative contracts + +Heading names in the wrapper are referenced by exact name in the core. Adding suffixes like `(REQUIRED)` or other annotations to heading text in templates or guides will break the exact-name contract silently at runtime. Treat section headings as API identifiers ā€” rename them only with the same care as renaming a function. + +### Preserve executable content during genericisation + +When migrating product-specific prompts to shared cores, bash scripts and procedural subsections are often generic despite appearing product-specific (they only contain path references that can be parameterised). Always diff the original vs genericised output section-by-section to catch accidentally dropped content. diff --git a/external/ag-shared/prompts/guides/website-astro-pages.md b/external/ag-shared/prompts/guides/website-astro-pages.md new file mode 100644 index 00000000000..a14e984055b --- /dev/null +++ b/external/ag-shared/prompts/guides/website-astro-pages.md @@ -0,0 +1,334 @@ +--- +targets: ['*'] +description: 'Astro page creation patterns, layout props, content collections, and code conventions for AG product websites' +globs: + [ + '**/src/pages/**/*.astro', + '**/src/layouts/**/*.astro', + ] +--- + +# Website Astro Pages Guide + +This guide covers Astro page creation patterns, layout props, content collections, and code conventions for AG product websites. + +## Project Overview + +- **Framework**: Astro 5 with React 18 for interactive components +- **Styling**: SCSS with CSS Modules + shared design system +- **Package Manager**: Yarn +- **Monorepo**: Nx-managed +- **Shared Components**: `external/ag-website-shared/src/components/` + +## Directory Structure + +``` +packages//src/ +ā”œā”€ā”€ pages/ # Astro page routes (*.astro files) +ā”œā”€ā”€ layouts/ +ā”‚ ā””ā”€ā”€ Layout.astro # Main page layout wrapper +ā”œā”€ā”€ components/ # Local React & Astro components +ā”œā”€ā”€ content/ # Content collections (data, docs) +ā”œā”€ā”€ pages-styles/ # Page-specific SCSS modules +ā”œā”€ā”€ stores/ # Nanostores (state management) +ā””ā”€ā”€ utils/ # Utility functions + +external/ag-website-shared/src/ +ā”œā”€ā”€ components/ # Shared components across AG products +ā”‚ ā”œā”€ā”€ license-pricing/ # Pricing page components +ā”‚ ā”œā”€ā”€ changelog/ # Changelog/pipeline components +ā”‚ ā”œā”€ā”€ community/ # Community page components +ā”‚ ā”œā”€ā”€ whats-new/ # Release notes components +ā”‚ ā”œā”€ā”€ landing-pages/ # Landing page components +ā”‚ ā”œā”€ā”€ footer/ # Footer component +ā”‚ ā”œā”€ā”€ site-header/ # Site header component +ā”‚ ā””ā”€ā”€ ... # Many more shared components +ā””ā”€ā”€ design-system/ # Design tokens and base styles +``` + +## Creating Standard Astro Pages + +### Page Location + +All pages go in `packages//src/pages/`. The file path determines the URL: + +| File Path | URL | +|-----------|-----| +| `pages/index.astro` | `/` | +| `pages/pricing.astro` | `/pricing` | +| `pages/community.astro` | `/community` | +| `pages/community/events.astro` | `/community/events` | + +### Pattern 1: Full Custom Page with Layout + +Use this for pages that need custom content and styling. + +```astro +--- +import Layout from '@layouts/Layout.astro'; +import styles from '@pages-styles/my-page.module.scss'; +import { urlWithBaseUrl } from '@utils/urlWithBaseUrl'; + +// Optional: Fetch data from content collections +import { getEntry, type CollectionEntry } from 'astro:content'; +const { data: navData } = (await getEntry('docsNav', 'nav')) as CollectionEntry<'docsNav'>; +--- + + +
+

My Page

+

Content goes here

+
+ +``` + +### Pattern 2: Wrapper Page (Delegates to Shared Component) + +Use this when a shared component handles all the page logic. + +```astro +--- +import { getEntry, type CollectionEntry } from 'astro:content'; +import WhatsNew from '@ag-website-shared/components/whats-new/pages/whats-new.astro'; + +// Note: version entry keys are product-specific (e.g. 'ag-grid-versions', 'ag-charts-versions') +const { data: versionsData } = (await getEntry('versions', '-versions')) as CollectionEntry<'versions'>; +const { data: docsNavData } = (await getEntry('docsNav', 'nav')) as CollectionEntry<'docsNav'>; +--- + + + +``` + +### Pattern 3: Minimal Wrapper (Simplest) + +For pages that just render a shared component with no data. + +```astro +--- +import Home from '@ag-website-shared/components/community/pages/home.astro'; +--- + + +``` + +### Pattern 4: Page with React Components + +Use this for interactive pages with client-side functionality. + +```astro +--- +import { LicensePricing } from '@ag-website-shared/components/license-pricing/LicensePricing'; +import Layout from '@layouts/Layout.astro'; +--- + + + + +``` + +### Pattern 5: Page with Docs Navigation + +Use this for pages that should show the documentation sidebar. + +```astro +--- +import { getEntry, type CollectionEntry } from 'astro:content'; +import Layout from '@layouts/Layout.astro'; +import { getFrameworkFromPath } from '@components/docs/utils/urlPaths'; +import { Pipeline } from '@ag-website-shared/components/changelog/Pipeline'; +import { DocsNavFromLocalStorage } from '@ag-website-shared/components/docs-navigation/DocsNavFromLocalStorage'; +import styles from '@ag-website-shared/components/changelog/changelog.module.scss'; +import classnames from 'classnames'; + +const path = Astro.url.pathname; +const framework = getFrameworkFromPath(path); +const { data: docsNavData } = (await getEntry('docsNav', 'nav')) as CollectionEntry<'docsNav'>; +--- + + +
+ + +
+

Pipeline

+ + +
+
+ +``` + +### Pattern 6: Standalone Page (No Layout) + +For special pages like demos that need full control. + +```astro +--- +import HeroDashboard from '@components/hero-dashboard/HeroDashboard.astro'; +import '@pages-styles/scratchpad.scss'; +import '@pages-styles/example-controls.css'; +--- + + + + + <Product Name> + + + + + +``` + +## Layout Component Props + +The `Layout.astro` component accepts these props: + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `title` | string | required | Page title (shown in browser tab) | +| `description` | string | metadata default | SEO meta description | +| `showSearchBar` | boolean | undefined | Show search in header | +| `showDocsNav` | boolean | undefined | Show docs navigation toggle | +| `hideHeader` | boolean | false | Hide the site header | +| `hideFooter` | boolean | false | Hide the site footer | + +## Content Collections + +Fetch data from content collections using Astro's `getEntry`: + +```astro +--- +import { getEntry, type CollectionEntry } from 'astro:content'; + +// Navigation data +const { data: docsNavData } = (await getEntry('docsNav', 'nav')) as CollectionEntry<'docsNav'>; +const { data: apiNavData } = (await getEntry('apiNav', 'nav')) as CollectionEntry<'apiNav'>; + +// Version data (entry key is product-specific, e.g. 'ag-grid-versions', 'ag-charts-versions') +const { data: versionsData } = (await getEntry('versions', '-versions')) as CollectionEntry<'versions'>; + +// Footer data +const { data: footerItems } = (await getEntry('footer', 'footer')) as CollectionEntry<'footer'>; + +// Metadata +const { data: metadata } = (await getEntry('metadata', 'metadata')) as CollectionEntry<'metadata'>; +--- +``` + +## Available Shared Components + +Key components from `@ag-website-shared/components/`: + +| Component | Import Path | Purpose | +|-----------|-------------|---------| +| `LicensePricing` | `license-pricing/LicensePricing` | Pricing page | +| `Pipeline` | `changelog/Pipeline` | Development pipeline | +| `WhatsNew` | `whats-new/pages/whats-new.astro` | Release notes | +| `DocsNavFromLocalStorage` | `docs-navigation/DocsNavFromLocalStorage` | Docs sidebar | +| `FrameworkTextAnimation` | `framework-text-animation/FrameworkTextAnimation` | Animated framework text | +| `LandingPageFWSelector` | `landing-pages/LandingPageFWSelector` | Framework selector | +| `Footer` | `footer/Footer` | Site footer | +| `SiteHeader` | `site-header/SiteHeader.astro` | Site header | + +## Utility Functions + +```typescript +// URL utilities +import { urlWithBaseUrl } from '@utils/urlWithBaseUrl'; +import { urlWithPrefix } from '@utils/urlWithPrefix'; + +// Add base URL to paths (base URL is product-specific) +urlWithBaseUrl('/example') // ā†’ '//example' (with configured base) + +// Add framework prefix +urlWithPrefix({ framework: 'react', url: './quick-start' }) // ā†’ '/react/quick-start' + +// Framework detection +import { getFrameworkFromPath } from '@components/docs/utils/urlPaths'; +const framework = getFrameworkFromPath(Astro.url.pathname); +``` + +## React Component Hydration + +When using React components in Astro pages, add hydration directives: + +| Directive | When to Use | +|-----------|-------------| +| `client:load` | Needs immediate interactivity (most common) | +| `client:idle` | Can wait until browser is idle | +| `client:visible` | Only when scrolled into view | +| (none) | Static content only, no JavaScript | + +```astro + + + + + + + + +``` + +## Path Aliases + +| Alias | Path | +|-------|------| +| `@components/*` | `src/components/*` | +| `@layouts/*` | `src/layouts/*` | +| `@pages-styles/*` | `src/pages-styles/*` | +| `@stores/*` | `src/stores/*` | +| `@utils/*` | `src/utils/*` | +| `@constants` | `src/constants.ts` | +| `@ag-website-shared/*` | `external/ag-website-shared/src/*` | + +## Code Style + +### Import Order + +1. Astro imports (`astro:content`) +2. External packages +3. Shared components (`@ag-website-shared/*`) +4. Local components/utils (`@components/*`, `@utils/*`) +5. Styles + +### Naming Conventions + +| Type | Convention | Example | +|------|------------|---------| +| Astro pages | kebab-case | `license-pricing.astro` | +| Components | PascalCase | `MyComponent.tsx` | +| Style modules | kebab-case | `my-page.module.scss` | +| CSS classes | camelCase | `.pageContainer` | + +## Common Tasks + +### Add a New Standard Page + +1. Create `src/pages/my-page.astro` +2. Import Layout and any needed components +3. Use standard design system classes where possible +4. Create `src/pages-styles/my-page.module.scss` only if custom styles needed + +### Use a Shared Component + +1. Check `external/ag-website-shared/src/components/` for available components +2. Import with `@ag-website-shared/components/...` +3. Add `client:load` if it's a React component needing interactivity diff --git a/external/ag-shared/prompts/guides/website-browser-testing.md b/external/ag-shared/prompts/guides/website-browser-testing.md new file mode 100644 index 00000000000..fcd239da0a8 --- /dev/null +++ b/external/ag-shared/prompts/guides/website-browser-testing.md @@ -0,0 +1,89 @@ +--- +targets: ['*'] +description: 'Chrome DevTools MCP browser testing workflow for AG product websites' +globs: + [ + '**/src/pages/**/*.astro', + '**/src/layouts/**/*.astro', + ] +--- + +# Website Browser Testing Guide + +Use Chrome DevTools MCP for browser testing and debugging AG product websites. + +## Available Tools + +| Tool | Purpose | +|------|---------| +| `mcp__chrome-devtools__browser_navigate` | Navigate to URL | +| `mcp__chrome-devtools__browser_snapshot` | Get accessibility tree snapshot | +| `mcp__chrome-devtools__browser_click` | Click elements | +| `mcp__chrome-devtools__browser_type` | Type text into elements | +| `mcp__chrome-devtools__browser_take_screenshot` | Capture screenshot | +| `mcp__chrome-devtools__browser_console_messages` | Get console messages with stack traces | +| `mcp__chrome-devtools__browser_network_requests` | Analyse network requests | +| `mcp__chrome-devtools__browser_evaluate` | Execute JavaScript | +| `mcp__chrome-devtools__browser_performance_record` | Record performance trace | +| `mcp__chrome-devtools__browser_emulate` | Emulate devices/network conditions | + +## Testing Workflow + +### 1. Start Development Server + +```bash +yarn nx dev +``` + +The dev server port is product-specific. Use `yarn nx dev` to start the server and check the output for the local URL. + +### 2. Navigate to Page + +``` +mcp__chrome-devtools__browser_navigate url="http://localhost:/my-page" +``` + +### 3. Check Console for Errors + +``` +mcp__chrome-devtools__browser_console_messages +``` + +### 4. Analyse Network Requests + +``` +mcp__chrome-devtools__browser_network_requests +``` + +### 5. Test Interactions + +``` +mcp__chrome-devtools__browser_click element="button with text 'Submit'" +mcp__chrome-devtools__browser_type element="email input" text="test@example.com" +``` + +### 6. Execute JavaScript + +``` +mcp__chrome-devtools__browser_evaluate expression="document.querySelector('h1').textContent" +``` + +## Testing Checklist + +- [ ] Page loads without console errors +- [ ] Content renders correctly +- [ ] Dark mode toggle works +- [ ] Responsive layout works +- [ ] Interactive components function +- [ ] Links navigate correctly +- [ ] Header/footer display properly +- [ ] No network errors + +## Device Emulation + +Test responsive layouts: + +``` +mcp__chrome-devtools__browser_emulate device="iPhone 14 Pro" +mcp__chrome-devtools__browser_emulate device="iPad" +``` diff --git a/external/ag-shared/prompts/guides/website-css.md b/external/ag-shared/prompts/guides/website-css.md new file mode 100644 index 00000000000..547b6db0ce1 --- /dev/null +++ b/external/ag-shared/prompts/guides/website-css.md @@ -0,0 +1,490 @@ +--- +targets: ['*'] +description: 'CSS architecture, design system, design tokens, utility classes, and styling patterns for AG product websites' +globs: + [ + '**/src/pages-styles/**/*.scss', + '**/src/pages-styles/**/*.css', + '**/src/components/**/*.scss', + 'external/ag-website-shared/src/design-system/**/*.scss', + ] +--- + +# Website CSS & Styling Guide + +This guide covers the CSS architecture, design system, design tokens, utility classes, and styling patterns used by AG product websites. + +## Design System + +### Location + +The website's design system is defined in a shared external package: + +``` +external/ag-website-shared/src/design-system/ +``` + +### File Structure + +| File | Purpose | +|------|---------| +| `_root.scss` | All CSS custom properties (colours, typography, layout, shadows) | +| `core/_variables.scss` | SCSS variables (spacing, selectors, transitions) | +| `core/_breakpoints.scss` | Responsive breakpoint values | +| `_layout.scss` | Layout utility classes | +| `_typography.scss` | Typography utility classes | +| `_color.scss` | Colour utility classes | +| `_interactions.scss` | Interactive state classes | +| `_base.scss` | Base element styles | + +### Using the Design System + +Always import the design system at the top of SCSS files: + +```scss +@use 'design-system' as *; +``` + +## CSS Custom Properties + +### How Variables Are Organised + +The design system uses CSS custom properties (variables) organised into semantic categories: + +```scss +:root { + // Abstract colours (raw palette) + --color-gray-50: #f9fafb; + --color-gray-100: #f2f4f7; + // ... through gray-950 + + --color-brand-50: #f4f8ff; + --color-brand-100: #e5effd; + // ... through brand-950 + + // Semantic colours (use these in components) + --color-bg-primary: var(--color-white); + --color-fg-primary: var(--color-gray-900); + --color-border-primary: var(--color-gray-300); +} +``` + +### Colour Palette Reference + +#### Grey Scale + +| Variable | Light Mode | Hex | +| ------------------ | ---------- | --------- | +| `--color-gray-25` | Lightest | `#fcfcfd` | +| `--color-gray-50` | | `#f9fafb` | +| `--color-gray-100` | | `#f2f4f7` | +| `--color-gray-200` | | `#eaecf0` | +| `--color-gray-300` | | `#d0d5dd` | +| `--color-gray-400` | | `#98a2b3` | +| `--color-gray-500` | | `#667085` | +| `--color-gray-600` | | `#475467` | +| `--color-gray-700` | | `#344054` | +| `--color-gray-800` | | `#182230` | +| `--color-gray-900` | | `#101828` | +| `--color-gray-950` | Darkest | `#0c111d` | + +#### Brand Colours (Blue) + +| Variable | Hex | +| ------------------- | --------- | +| `--color-brand-50` | `#f4f8ff` | +| `--color-brand-100` | `#e5effd` | +| `--color-brand-200` | `#d4e3f8` | +| `--color-brand-300` | `#a9c5ec` | +| `--color-brand-400` | `#3d7acd` | +| `--color-brand-500` | `#0e4491` | +| `--color-brand-600` | `#0042a1` | +| `--color-brand-700` | `#00388f` | +| `--color-brand-800` | `#002e7e` | +| `--color-brand-900` | `#00246c` | +| `--color-brand-950` | `#001a5a` | + +#### Warning Colours (Orange/Yellow) + +| Variable | Hex | +| --------------------- | --------- | +| `--color-warning-50` | `#fffaeb` | +| `--color-warning-100` | `#fef0c7` | +| `--color-warning-200` | `#fedf89` | +| `--color-warning-300` | `#fec84b` | +| `--color-warning-400` | `#fdb022` | +| `--color-warning-500` | `#f79009` | +| `--color-warning-600` | `#dc6803` | +| `--color-warning-700` | `#b54708` | +| `--color-warning-800` | `#93370d` | +| `--color-warning-900` | `#7a2e0e` | +| `--color-warning-950` | `#4e1d09` | + +#### Special Colours + +| Variable | Hex | Usage | +| ------------------ | ------------------------------------ | --------------------- | +| `--color-success` | `#28a745` (light) / `#64ea82` (dark) | Success states | +| `--color-positive` | `#28a745` | Positive indicators | +| `--color-negative` | `#dc3545` | Error/negative states | + +## Standard CSS Utility Classes + +**Always prefer using standard design system classes over custom styles.** These classes are globally available and ensure consistency across the site. + +### Layout Classes + +Use these for page structure and grid layouts: + +| Class | Purpose | +|-------|---------| +| `.layout-grid` | Flexbox grid container with standard gap and max-width | +| `.layout-page-max-width` | Full width constrained to max page width | +| `.layout-max-width-small` | Narrower content width with horizontal padding | + +**Column Classes (4-column grid):** +- `.column-1-4`, `.column-2-4`, `.column-3-4`, `.column-4-4` + +**Column Classes (6-column grid):** +- `.column-1-6` through `.column-6-6` + +**Column Classes (12-column grid):** +- `.column-1-12` through `.column-12-12` + +```astro +
+
Main content
+
Sidebar
+
+``` + +### Typography Classes + +| Class | Font Size | Use For | +|-------|-----------|---------| +| `.text-2xs` | 10px | Fine print | +| `.text-xs` | 12px | Captions, labels | +| `.text-sm` | 14px | Secondary text | +| `.text-base` | 16px | Body text (default) | +| `.text-lg` | 20px | Subheadings | +| `.text-xl` | 24px | Section headings | +| `.text-2xl` | 32px | Page headings | +| `.text-3xl` | 40px | Hero headings | + +**Weight Classes:** +- `.text-regular` (400) +- `.text-semibold` (600) +- `.text-bold` (700) + +**Other:** +- `.text-monospace` - Monospace font family + +```astro +

Page Title

+

Body content here.

+code example +``` + +### Colour Classes + +| Class | Purpose | +|-------|---------| +| `.text-secondary` | Secondary foreground colour | +| `.text-tertiary` | Tertiary foreground colour | + +### Interaction Classes + +| Class | Purpose | +|-------|---------| +| `.collapse` | Hidden when not `.show` | +| `.collapsing` | Animating collapse transition | +| `.no-transitions` | Disable all transitions | +| `.no-overflow-anchor` | Prevent scroll anchoring | + +### Example: Using Standard Classes + +```astro +
+

Welcome

+

+ Introduction paragraph with secondary styling. +

+ +
+
+

Left Column

+
+
+

Right Column

+
+
+
+``` + +## Dark Mode + +### How Dark Mode Works + +Dark mode is triggered by the `data-dark-mode="true"` attribute on the `` element: + +```scss +html[data-dark-mode='true'] { + --color-bg-primary: color-mix(in srgb, var(--color-gray-800), var(--color-gray-900) 50%); + --color-fg-primary: var(--color-white); + // ... other overrides +} +``` + +### Dark Mode in SCSS Modules + +Use the `$selector-darkmode` SCSS variable for dark mode overrides in component styles: + +```scss +.myElement { + background-color: var(--color-bg-primary); + + #{$selector-darkmode} & { + background-color: var(--color-bg-secondary); + } +} +``` + +### Key Dark Mode Colours + +| Semantic Variable | Light Mode | Dark Mode | +| -------------------------- | ---------- | ---------------------------------------- | +| `--color-bg-primary` | `#ffffff` | Mix of `#182230` + `#101828` | +| `--color-bg-secondary` | `#f9fafb` | `#344054` | +| `--color-bg-tertiary` | `#f2f4f7` | `#182230` | +| `--color-fg-primary` | `#101828` | `#ffffff` | +| `--color-fg-secondary` | `#344054` | `#d0d5dd` | +| `--color-border-primary` | `#d0d5dd` | `#344054` | +| `--color-border-secondary` | `#eaecf0` | Mix of `#344054` + bg-primary | +| `--color-link` | `#0e4491` | `#a9c5ec` | + +### Detecting Dark Mode in JavaScript + +```typescript +// Check data attribute (preferred) +const isDark = document.documentElement.getAttribute('data-dark-mode') === 'true'; + +// Or check for dark mode class (fallback) +const isDark = document.documentElement.classList.contains('dark'); +``` + +### Creating Theme-Aware Components + +Use CSS custom properties that react to `data-dark-mode`: + +```css +/* Define variables for both modes */ +:root { + --my-component-bg: #ffffff; + --my-component-text: #101828; +} + +[data-dark-mode='true'] { + --my-component-bg: #182230; + --my-component-text: #d0d5dd; +} + +/* Use variables in component */ +.my-component { + background: var(--my-component-bg); + color: var(--my-component-text); +} +``` + +This approach ensures instant theme switching without JavaScript re-rendering. + +## Semantic Colour Categories + +### Background Colours (`--color-bg-*`) + +- `--color-bg-primary`: Main content background +- `--color-bg-secondary`: Secondary/elevated surfaces +- `--color-bg-tertiary`: Subtle backgrounds +- `--color-bg-toolbar`: Toolbar backgrounds +- `--color-bg-code`: Code block backgrounds + +### Foreground/Text Colours (`--color-fg-*`) + +- `--color-fg-primary`: Primary text +- `--color-fg-secondary`: Secondary/muted text +- `--color-fg-tertiary`: Subtle text +- `--color-fg-disabled`: Disabled state text + +### Border Colours (`--color-border-*`) + +- `--color-border-primary`: Primary borders +- `--color-border-secondary`: Subtle borders +- `--color-border-tertiary`: Very subtle borders + +### Link Colours (`--color-link*`) + +- `--color-link`: Default link colour +- `--color-link-hover`: Link hover state + +## Design Tokens Reference + +### Spacing (SCSS variables from `core/_variables.scss`) + +| Variable | Value | +|----------|-------| +| `$spacing-size-1` | 4px | +| `$spacing-size-2` | 8px | +| `$spacing-size-3` | 12px | +| `$spacing-size-4` | 16px | +| `$spacing-size-5` | 20px | +| `$spacing-size-6` | 24px | +| `$spacing-size-8` | 32px | +| `$spacing-size-10` | 40px | +| `$spacing-size-12` | 48px | +| `$spacing-size-16` | 64px | +| `$spacing-size-20` | 80px | +| `$spacing-size-24` | 96px | + +### Breakpoints (SCSS variables from `core/_breakpoints.scss`) + +| Variable | Value | Use For | +|----------|-------|---------| +| `$breakpoint-hero-small` | 620px | Small hero layouts | +| `$breakpoint-hero-large` | 1020px | Large hero layouts | +| `$breakpoint-landing-page-medium` | 1020px | Landing pages | +| `$breakpoint-docs-nav-medium` | 1052px | Docs navigation | +| `$breakpoint-pricing-small` | 620px | Pricing page | +| `$breakpoint-pricing-medium` | 820px | Pricing page | +| `$breakpoint-pricing-large` | 1260px | Pricing page | + +### Typography (CSS variables from `_root.scss`) + +| Variable | Value | +|----------|-------| +| `--text-fs-2xs` | 10px | +| `--text-fs-xs` | 12px | +| `--text-fs-sm` | 14px | +| `--text-fs-base` | 16px | +| `--text-fs-lg` | 20px | +| `--text-fs-xl` | 24px | +| `--text-fs-2xl` | 32px | +| `--text-fs-3xl` | 40px | +| `--text-lh-tight` | 1.2 | +| `--text-regular` | 400 | +| `--text-semibold` | 600 | +| `--text-bold` | 700 | + +### Layout (CSS variables from `_root.scss`) + +| Variable | Description | +|----------|-------------| +| `--layout-gap` | Grid gap (32px) | +| `--layout-max-width` | Max page width (1800px) | +| `--layout-max-width-small` | Narrow content width (1240px) | +| `--layout-horizontal-margins` | Side margins | + +### Border Radius + +- `--radius-xs` (4px), `--radius-sm` (6px), `--radius-md` (8px), `--radius-lg` (10px), `--radius-xl` (12px), `--radius-2xl` (16px) + +### Shadows + +- `--shadow-xs`, `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl` + +## Creating Custom Page Styles + +Only create custom styles when standard classes don't meet your needs. Create SCSS modules in `packages//src/pages-styles/`: + +```scss +// my-page.module.scss +@use 'design-system' as *; + +.heroSection { + padding-top: $spacing-size-16; + background-color: var(--color-bg-site-header); + + // Dark mode support + #{$selector-darkmode} & { + background-color: var(--color-bg-secondary); + } + + // Responsive + @media screen and (min-width: $breakpoint-hero-large) { + padding-top: $spacing-size-24; + } +} +``` + +## Using Styles in Astro + +```astro +--- +import styles from '@pages-styles/my-page.module.scss'; +import classnames from 'classnames'; +--- + +
+
+

Title

+
+
+``` + +## Component Styling Patterns + +### Using SCSS Modules + +The website uses CSS/SCSS modules for component styling: + +```scss +// MyComponent.module.scss +.container { + background: var(--color-bg-primary); + border: 1px solid var(--color-border-primary); + color: var(--color-fg-primary); +} +``` + +## Best Practices + +### DO: + +- Use semantic variables (`--color-bg-primary`) not raw colours (`--color-gray-50`) +- Define component-specific variables that reference design system variables +- Use `[data-dark-mode="true"]` selector or `#{$selector-darkmode}` for dark mode overrides +- Test components in both light and dark modes +- Prefer standard design system utility classes over custom styles + +### DON'T: + +- Hardcode hex colours directly in components +- Use `prefers-color-scheme` media query (the site uses explicit `data-dark-mode`) +- Assume light mode is the default without testing dark mode + +## Adding New Theme-Aware Styles + +When creating new components or features that need to support both themes: + +1. **Define CSS variables** in a `