style: fix markdown table alignment in openspec docs - #65
Conversation
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Summary of ChangesHello @alexey1312, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request addresses stylistic inconsistencies and formatting violations within the openspec design documentation. The primary goal was to enhance readability and adhere to established formatting standards by correcting markdown table alignment and resolving dprint formatting issues. These changes ensure a cleaner and more consistent presentation of technical specifications. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request addresses markdown formatting issues by aligning tables in several openspec design documents. The changes are purely stylistic and improve readability. I've identified an improvement opportunity related to the repository's style guide for tabular data. The markdown tables could be converted to the TOON format as specified in the style guide. I've left comments on each file with a markdown table suggesting this change.
| | Option | Pros | Cons | | ||
| | ---------------------------- | --------------------------------------- | ------------------------------ | | ||
| | Add collection to TerminalUI | Single point of interception | Adds state to stateless class | | ||
| | Separate WarningCollector | Clean separation, follows actor pattern | Must wire into export commands | | ||
| | Intercept at queueLogMessage | No TerminalUI changes | Only works in batch mode | |
There was a problem hiding this comment.
The repository style guide specifies using the TOON format for tabular data. While this PR fixes the markdown table alignment, this is a good opportunity to convert this table, and others in the file, to the TOON format to adhere to the convention.
For example, this table could be converted to:
options[3]{option,pros,cons}:
"Add collection to TerminalUI","Single point of interception","Adds state to stateless class"
"Separate WarningCollector","Clean separation, follows actor pattern","Must wire into export commands"
"Intercept at queueLogMessage","No TerminalUI changes","Only works in batch mode"
Note: The TOON format specification in the style guide doesn't specify how to handle commas within values. Please verify the correct approach, for example by using quotes or rephrasing the content to avoid commas.
References
- The style guide requires using TOON format for all tabular data to reduce token usage and improve parsing consistency, with a specific exception for
tasks.mdfiles. (link)
| | Approach | Pros | Cons | | ||
| | ------------------------------- | --------------------------------------------- | --------------------------------------------------------- | | ||
| | Resolver module (spec-native) | Fully spec-compliant theming, fallback chains | Multi-file, complex architecture, overkill for simple L/D | | ||
| | `$extensions` modes (chosen) | Single file, mode relationship explicit | Vendor extension, requires ExFig-aware tool support | | ||
| | Separate file per mode | Clean separation, each file is spec-pure | Multiple files to manage, harder to diff | | ||
| | `$value` as mode dict (current) | Compact | Violates spec (`$value` must be a color object) | |
There was a problem hiding this comment.
According to the repository style guide, tabular data should use the TOON format. This markdown table, and others in this file, should be converted to TOON format to align with the project's conventions.
For example, this table could be converted to:
alternatives[4]{approach,pros,cons}:
"Resolver module (spec-native)","Fully spec-compliant theming, fallback chains","Multi-file, complex architecture, overkill for simple L/D"
"$extensions modes (chosen)","Single file, mode relationship explicit","Vendor extension, requires ExFig-aware tool support"
"Separate file per mode","Clean separation, each file is spec-pure","Multiple files to manage, harder to diff"
"$value as mode dict (current)","Compact","Violates spec ($value must be a color object)"
Note: The TOON format as specified in the style guide does not detail how to handle commas within values. Please verify how to correctly format these values in TOON, for example by using quotes or rephrasing.
References
- The style guide requires using TOON format for all tabular data to reduce token usage and improve parsing consistency, with a specific exception for
tasks.mdfiles. (link)
| | W3C Token Type | ExFigCore Model | `$value` Format | | ||
| | -------------- | --------------- | --------------------------------------------------------- | | ||
| | `color` | `Color` | Object: `{colorSpace, components, alpha?, hex?}` | | ||
| | `typography` | `TextStyle` | Object: `{fontFamily, fontSize, fontWeight, lineHeight?}` | | ||
| | `dimension` | (numeric value) | Object: `{value, unit}` — unit is `"px"` or `"rem"` | | ||
| | `number` | (numeric value) | Plain JSON number | | ||
| | `fontFamily` | (string value) | String or array of strings | | ||
| | `fontWeight` | (numeric value) | Number (1–1000) or string alias (e.g., "bold") | |
There was a problem hiding this comment.
The repository style guide specifies using the TOON format for tabular data. This markdown table should be converted to TOON format to adhere to the project's conventions.
Note: The TOON format as specified in the style guide does not detail how to handle commas within values. This table contains several cells with commas. Please verify how to correctly format these values in TOON, for example by using quotes or rephrasing.
References
- The style guide requires using TOON format for all tabular data to reduce token usage and improve parsing consistency, with a specific exception for
tasks.mdfiles. (link)
1 participant
Summary
Test plan
mise run format-checkpasses locally🤖 Generated with Claude Code