feat(dialtone-docs): DDT-1622 add AI documentation package — content, validation, and templates#1051
Open
belumontoya wants to merge 18 commits intostagingfrom
Open
feat(dialtone-docs): DDT-1622 add AI documentation package — content, validation, and templates#1051belumontoya wants to merge 18 commits intostagingfrom
belumontoya wants to merge 18 commits intostagingfrom
Conversation
This commit contains the planning and discovery phase documentation for implementing AI-friendly documentation in Dialtone. Includes: - Analysis of current documentation system (HOW_DOCS_WORK.md) - Research findings and brainstorming (BRAINSTORM_AI_GEO_DOCS.md) - Planning methodology documentation (PLANNING_METHODOLOGY.md) - Detailed Phase 1 implementation plan (PHASE_1_IMPLEMENTATION_PLAN.md) - Executive summary and navigation (PLANNING_INDEX.md, PLANNING_EXECUTIVE_SUMMARY.md) Key decisions: - Two-track approach: Internal AI Standards + External GEO - Root docs/ for AI context, public site for GEO optimization - Test-driven documentation with automated validation - Foundation-first approach (structure, tests, templates before content) This documentation explains WHY and HOW we planned, not implementation. No code changes or actual documentation structure created yet. Phase 1 execution will follow in subsequent commits.
Merged best practices from design-studio and beacon-app repos into single authoritative standards document. Key sections: - Three core principles: Searchability, Completeness, Structure - Content Quality guidelines (substantive content, no placeholders) - File Naming Conventions for all 5 categories - Complete directory structure for docs/ - External GEO Reference (6 principles for public docs) - Validation guidelines (automated vs manual) - Tools & Resources for documentation authors - Enhanced checklist (20 items) This provides complete guidance for both internal AI context docs and external GEO optimization.
Add comprehensive 7-day implementation plan for new packages/dialtone-docs/ package that generates AI-discoverable documentation. Plan includes incremental milestones for test infrastructure, content validation, documentation generation, MCP integration, and CI/CD. Also includes adapted Task 2.1 from original planning phase.
Create new packages/dialtone-docs/ package with: - Basic directory structure (src/, tests/helpers/, tests/tests/) - package.json with dependencies (gray-matter, glob, handlebars, vitest) - Build and test scripts configuration This is Milestone 1, Tasks 1-2 of the implementation plan.
Wiz Scan Summary
|
| Scanner | Findings |
|---|---|
 |
51    |
 |
- |
 |
- |
 |
- |
 |
- |
 |
- |
| Total | 51 |
To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.
Add project.json with build and test targets for NX orchestration. Enables running package tasks via nx run commands and integrates with monorepo caching and dependency graph.
Add markdownParser.js, fileReader.js, and frontmatterParser.js test helpers plus vite.config.js and updated plan file. Completes the test infrastructure layer for the dialtone-docs package. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add structure.test.js as a development scaffold test to validate package setup during active development. All 9 tests pass via nx run dialtone-docs:test. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add architecture-monorepo-structure.md and architecture-build-system.md with AI-discoverable frontmatter, real package names, and detailed guidance on adding new packages to the monorepo. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add INDEX.md, monorepo structure, build system, documentation system, and design token pipeline docs to src/content/architecture/.
Adds 5 development workflow guides and an index under packages/dialtone-docs/src/content/development/: - Component workflow: Yeoman generator, 8-file structure, JSDoc conventions for props/slots/events, constants pattern, data-qa - CSS utilities: static LESS vs PostCSS generator approaches, naming convention, responsive/hover/focus variants, Gulp build pipeline - Design tokens: raw vs semantic token distinction, JSON format, token reference syntax, build steps after changes - Icons: SVG requirements, category structure, keywords, Gulp pipeline that generates Vue components, size variants - Testing: Vitest setup, coverage thresholds, standard test pattern, mount vs shallowMount, shared fixtures and assertion helpers
Adds 6 workflow documentation files and an index under
packages/dialtone-docs/src/content/workflows/:
- Release process: Tuesday 10AM UTC cron, semantic-release per
package, tag format {name}/v{version}, changelog plugins, npmPublish
disabled, staging-to-production fast-forward auto-merge
- Branch strategy: staging as main dev branch, all PRs target staging,
production only updated via release, deploy preview URL patterns,
required checks before merge
- Conventional commits: full format with JIRA requirement, 11 allowed
types, version bump mapping, breaking change syntax, custom
@dialpad/conventional-changelog-angular behavior
- Component lifecycle: ready/beta/planned status values, frontmatter
fields, component status page rendering, planned nav items
- Figma sync: both sync script directions, env vars required, Tokens
Studio vs Style Dictionary format, GitHub Actions workflows
- CI pipeline: all workflows with triggers, commands, required checks,
GCP deployment destinations, secrets reference table
belumontoya
requested review from
Brad Paugh (braddialpad),
Francis Rupert (francisrupert),
Ignacio Ropolo (iropolo) and
Nina Repetto (ninarepetto)
as code owners
Contributor
Author
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 605e732d51
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "codex (@codex) address that feedback".
…cessibility checklist
… and GEO optimization
…lengths - Add component.md.hbs and architecture.md.hbs templates - Add frontmatter, searchability, and completeness validation tests - Fix ai_summary fields exceeding 150-char limit across 6 content files - Fix YAML parse error in architecture-documentation-system.md frontmatter - All 26 tests pass
belumontoya
changed the title
belumontoya
changed the title
…tion extraction, sync lockfile - Remove build target from project.json (src/generators/build.mjs is Milestone 3 work, not yet created) - Fix extractSections to end sections at same-or-higher level headings, matching the documented contract - Commit updated pnpm-lock.yaml so CI --frozen-lockfile passes
Planning, brainstorming, and discovery files served their purpose during Milestones 1-2 and are not part of the shipping package. AI_DOCUMENTATION_STANDARDS.md was already split into standard-ai-documentation.md and standard-geo-optimization.md inside packages/dialtone-docs/src/content/standards/.
…it isFilePath Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Brad Paugh (@braddialpad) thank you for the thorough review |
Brad Paugh (braddialpad)
approved these changes
Mar 12, 2026
Contributor
Brad Paugh (braddialpad)
left a comment
Brad Paugh (braddialpad)
left a comment
There was a problem hiding this comment.
Looks good, I think the only remaining change that needs to be made is the beforeAll. Pre-approving
Contributor
|
I was thinking while checking the PR, about Ai-docs and context we provide to AI to be up to date with changes. I will probably never check this docs to be honest 🥴🥴 |
Contributor
Author
I have another PR coming, where I'm adding skills and tools to help syncronize docs, also this should evolve in having the docs automatically made |
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🛠️ Type Of Change
📖 Description
Adds
packages/dialtone-docs/, a new package that provides AI-discoverable documentation for the Dialtone design system. This PR covers Milestones 1-2 of a 7-milestone plan — package foundation and content authoring. No other package depends on this yet, so merging carries zero risk.What this adds
Package infrastructure (
packages/dialtone-docs/):package.jsonwith dependencies (gray-matter, glob, handlebars, vitest)project.jsonfor NX build and test targetsvite.config.jswith Vitest configuration and path aliases22 content files across 5 categories, all researched from the actual codebase:
architecture/development/workflows/reference/standards/2 Handlebars templates for generating new docs:
component.md.hbs— Component documentation templatearchitecture.md.hbs— Architecture documentation template3 test helpers for parsing and validating markdown content:
fileReader.js— Finds content files by glob patternfrontmatterParser.js— Parses YAML frontmatter via gray-mattermarkdownParser.js— Extracts headings, sections, and stripped text from markdown4 test suites (26 tests, all passing):
structure.test.js— Package config, directories, test helpers existfrontmatter.test.js— YAML frontmatter validation (required fields, types, keyword count, ai_summary length)searchability.test.js— Content uses actual package names and technical terms, no placeholder contentcompleteness.test.js— All category directories, INDEX files, content docs, and templates existPlanning documents in
docs/:🧪 How To Test
The tests validate:
.mdfile has valid YAML frontmatter with required fields (type,category,keywordswith 3+ items,ai_summary≤ 150 chars)No build step is needed yet — that's Milestone 3. This package only has tests at this stage.
💡 Context
Problem: AI assistants need structured, searchable documentation to help developers use Dialtone effectively. Current docs are optimized for human reading on dialtone.dialpad.com but lack the structure for AI consumption.
Approach: A dedicated package that validates and generates AI-optimized documentation following three principles:
Design decisions:
architecture-build-system.md)build-dialtone-vue-docs.mjs)🔮 Future Milestones (separate branch)
After merge, a
docs/planning-phase2branch will implement:ai-docs.json)search_docstool)📝 Checklist
pnpm nx run dialtone-docs:test)