Skip to content

Commit e0cc84f

Browse files
droshevdroshev
committed
docs: more ai docs improvements
1 parent bbbaacc commit e0cc84f

File tree

145 files changed

+17663
-932
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

145 files changed

+17663
-932
lines changed

‎.github/workflows/ai-documentation.yml‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,14 +40,20 @@ jobs:
4040
- name: Generate Component Relationships
4141
run: yarn generate:relationships
4242

43+
- name: Generate Accessibility Data
44+
run: yarn generate:accessibility
45+
46+
- name: Generate Design Tokens
47+
run: yarn generate:design-tokens
48+
4349
- name: Run AI Documentation Tests
4450
run: yarn test:ai-docs
4551

4652
- name: Check for documentation changes
4753
id: check-changes
4854
run: |
4955
git add -N docs/
50-
if git diff --exit-code docs/component-catalog.json docs/component-relationships.json docs/schemas/; then
56+
if git diff --exit-code docs/component-catalog.json docs/component-relationships.json docs/schemas/ docs/accessibility.json docs/design-tokens.json; then
5157
echo "status=up-to-date" >> $GITHUB_OUTPUT
5258
echo "::notice::AI documentation is up to date"
5359
else
@@ -62,7 +68,7 @@ jobs:
6268
echo "" >> $GITHUB_STEP_SUMMARY
6369
echo "The following AI documentation files need updating:" >> $GITHUB_STEP_SUMMARY
6470
echo "" >> $GITHUB_STEP_SUMMARY
65-
git diff --stat docs/component-catalog.json docs/component-relationships.json docs/schemas/ >> $GITHUB_STEP_SUMMARY
71+
git diff --stat docs/component-catalog.json docs/component-relationships.json docs/schemas/ docs/accessibility.json docs/design-tokens.json >> $GITHUB_STEP_SUMMARY
6672
echo "" >> $GITHUB_STEP_SUMMARY
6773
echo "### Component Catalog Changes" >> $GITHUB_STEP_SUMMARY
6874
echo '```diff' >> $GITHUB_STEP_SUMMARY
@@ -72,14 +78,14 @@ jobs:
7278
- name: Fail if documentation is outdated (PR only)
7379
if: github.event_name == 'pull_request' && steps.check-changes.outputs.status == 'outdated'
7480
run: |
75-
echo "::error::AI documentation is outdated. Please run 'yarn generate:ai-metadata && yarn generate:relationships' and commit the changes."
81+
echo "::error::AI documentation is outdated. Please run 'yarn generate:ai-docs' and commit the changes."
7682
exit 1
7783
7884
- name: Commit documentation updates (main branch only)
7985
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.check-changes.outputs.status == 'outdated'
8086
run: |
8187
git config --global user.name 'github-actions[bot]'
8288
git config --global user.email 'github-actions[bot]@users.noreply.github.com'
83-
git add docs/component-catalog.json docs/component-relationships.json docs/schemas/
89+
git add docs/component-catalog.json docs/component-relationships.json docs/schemas/ docs/accessibility.json docs/design-tokens.json
8490
git commit -m "chore(docs): update AI documentation [ci skip]"
8591
git push

‎CLAUDE.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -100,10 +100,10 @@ CSS component library for SAP Design System. Framework-agnostic, works with any
100100
### Select/Dropdown
101101
```html
102102
<div class="fd-select">
103-
<div class="fd-select__control">
103+
<div class="fd-select__control" role="combobox" aria-expanded="false" aria-haspopup="listbox" tabindex="0">
104104
<span class="fd-select__text-content">Select an option</span>
105-
<span class="fd-select__button">
106-
<span class="sap-icon--slim-arrow-down"></span>
105+
<span class="fd-button fd-button--transparent fd-select__button">
106+
<i class="sap-icon--slim-arrow-down" role="presentation"></i>
107107
</span>
108108
</div>
109109
</div>
@@ -112,16 +112,19 @@ CSS component library for SAP Design System. Framework-agnostic, works with any
112112
### Checkbox & Radio
113113
```html
114114
<!-- Checkbox -->
115-
<div class="fd-checkbox">
116-
<input type="checkbox" class="fd-checkbox__input" id="cb1">
117-
<label class="fd-checkbox__label" for="cb1">Option</label>
118-
</div>
115+
<input type="checkbox" class="fd-checkbox" id="cb1">
116+
<label class="fd-checkbox__label" for="cb1">
117+
<span class="fd-checkbox__checkmark" aria-hidden="true"></span>
118+
<span class="fd-checkbox__label-container">
119+
<span class="fd-checkbox__text">Option</span>
120+
</span>
121+
</label>
119122

120123
<!-- Radio -->
121-
<div class="fd-radio">
122-
<input type="radio" class="fd-radio__input" id="r1" name="group">
123-
<label class="fd-radio__label" for="r1">Option</label>
124-
</div>
124+
<input type="radio" class="fd-radio" id="r1" name="group">
125+
<label class="fd-radio__label" for="r1">
126+
<span class="fd-radio__text">Option</span>
127+
</label>
125128
```
126129

127130
### Table
@@ -304,4 +307,8 @@ Available in `fundamental-styles/dist/theming/`:
304307
- **Full component list**: [docs/ai-component-index.md](docs/ai-component-index.md)
305308
- **Component schemas**: [docs/schemas/*.json](docs/schemas/)
306309
- **Utility classes**: [docs/utility-classes.json](docs/utility-classes.json)
310+
- **Complete HTML patterns**: [docs/html-examples.json](docs/html-examples.json) (table, forms, dialogs, navigation)
311+
- **Modifier combinations**: [docs/modifier-rules.json](docs/modifier-rules.json) (which modifiers conflict)
312+
- **Accessibility patterns**: [docs/accessibility.json](docs/accessibility.json) (ARIA for 72 components)
313+
- **Design tokens**: [docs/design-tokens.json](docs/design-tokens.json) (1,522 CSS variables)
307314
- **Visual examples**: https://sap.github.io/fundamental-styles/

‎docs/AI_DOCUMENTATION_SYSTEM.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,10 @@ yarn test:ai-docs # Run validation tests
4242
| schemas/*.schema.json | 120 JSON validation schemas |
4343
| component-relationships.json | 307 relationships, analytics |
4444
| component-graph.md | Mermaid visualization |
45+
| html-examples.json | 10 complete HTML patterns |
46+
| modifier-rules.json | Mutually exclusive modifier rules |
47+
| accessibility.json | ARIA patterns for 72 components |
48+
| design-tokens.json | 1,522 CSS custom properties |
4549

4650
## Features
4751

@@ -116,7 +120,7 @@ Fully automated via CI/CD. Manual updates only needed for:
116120
## Documentation
117121

118122
- [AI_DOCUMENTATION_TESTS.md](AI_DOCUMENTATION_TESTS.md) - Test suite
119-
- [FUTURE_ENHANCEMENTS.md](FUTURE_ENHANCEMENTS.md) - Identified gaps and priorities
123+
- [AI_DOCUMENTATION_VALIDATION.md](AI_DOCUMENTATION_VALIDATION.md) - Validation report and fixes
120124

121125
---
122126

‎docs/AI_DOCUMENTATION_VALIDATION.md‎

Lines changed: 170 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,25 @@
1010

1111
| Artifact | Status | Notes |
1212
|----------|--------|-------|
13-
| component-catalog.json | ✅ Accurate | 120 components, 747 modifiers |
13+
| component-catalog.json | ✅ Accurate | 120 components, 747 modifiers, 114 with use cases |
1414
| utility-classes.json | ✅ Accurate | 229 utility classes |
15+
| component-use-cases.json | ✅ Accurate | 94 component use cases defined |
1516
| schemas/*.json | ✅ Accurate | No hallucinated or incomplete modifiers |
16-
| CLAUDE.md | ✅ Accurate | All class names verified |
17+
| CLAUDE.md | ✅ Accurate | All class names and HTML examples verified |
1718
| llms.txt | ✅ Accurate | All links verified |
1819
| ai-component-index.md | ✅ Accurate | Component count updated to 120 |
20+
| design-tokens.json | ✅ Accurate | 1,522 tokens from SAP theming (P2.1) |
21+
| modifier-rules.json | ✅ Accurate | 8 components with mutual exclusion rules (P2.2) |
22+
| html-examples.json | ✅ Fixed | 10 patterns, fixed side-nav classes (P2.3) |
23+
| accessibility.json | ✅ Accurate | 72 components with ARIA metadata (P1.1) |
1924

2025
---
2126

2227
## Fixes Applied
2328

24-
### 1. Fixed generate-ai-metadata.js
29+
### Round 1 (2026-02-14 AM)
30+
31+
#### 1. Fixed generate-ai-metadata.js
2532

2633
**Issue**: Script was including modifiers from imported component files (not mixins), causing hallucination.
2734

@@ -34,13 +41,13 @@
3441

3542
**Also fixed**: Filter out incomplete modifiers ending with `-` (from Sass interpolation patterns like `&--accent-color-#{$set-name}`)
3643

37-
### 2. Fixed CLAUDE.md
44+
#### 2. Fixed CLAUDE.md utility class
3845

3946
**Issue**: Incorrect utility class name
4047
- **Before**: `sap-flex--align-center`
4148
- **After**: `sap-flex--align-items-center`
4249

43-
### 3. Fixed ai-component-index.md
50+
#### 3. Fixed ai-component-index.md
4451

4552
**Issue**: Component count showed 117 instead of 120
4653

@@ -49,14 +56,129 @@
4956
- Line 25: Package table
5057
- Line 421: Statistics section
5158

52-
### 4. Fixed generate-utility-classes.js
59+
#### 4. Fixed generate-utility-classes.js
5360

5461
**Issue**: Missing shadow utility classes from `$sap-box-shadow-types`
5562

5663
**Added**:
5764
- `sap-has-shadow-color`
5865
- `sap-has-shadow-inverted-color`
5966

67+
### Round 2 (2026-02-14 PM)
68+
69+
#### 5. Fixed CLAUDE.md Checkbox Example
70+
71+
**Issue**: Wrong HTML structure for checkbox component
72+
73+
**Before** (incorrect):
74+
```html
75+
<div class="fd-checkbox">
76+
<input type="checkbox" class="fd-checkbox__input" id="cb1">
77+
<label class="fd-checkbox__label" for="cb1">Option</label>
78+
</div>
79+
```
80+
81+
**After** (correct):
82+
```html
83+
<input type="checkbox" class="fd-checkbox" id="cb1">
84+
<label class="fd-checkbox__label" for="cb1">
85+
<span class="fd-checkbox__checkmark" aria-hidden="true"></span>
86+
<span class="fd-checkbox__label-container">
87+
<span class="fd-checkbox__text">Option</span>
88+
</span>
89+
</label>
90+
```
91+
92+
#### 6. Fixed CLAUDE.md Radio Example
93+
94+
**Issue**: Wrong HTML structure for radio component
95+
96+
**Before** (incorrect):
97+
```html
98+
<div class="fd-radio">
99+
<input type="radio" class="fd-radio__input" id="r1" name="group">
100+
<label class="fd-radio__label" for="r1">Option</label>
101+
</div>
102+
```
103+
104+
**After** (correct):
105+
```html
106+
<input type="radio" class="fd-radio" id="r1" name="group">
107+
<label class="fd-radio__label" for="r1">
108+
<span class="fd-radio__text">Option</span>
109+
</label>
110+
```
111+
112+
#### 7. Fixed CLAUDE.md Select Example
113+
114+
**Issue**: Missing required attributes and incorrect button structure
115+
116+
**Before** (incomplete):
117+
```html
118+
<div class="fd-select">
119+
<div class="fd-select__control">
120+
<span class="fd-select__text-content">Select an option</span>
121+
<span class="fd-select__button">
122+
<span class="sap-icon--slim-arrow-down"></span>
123+
</span>
124+
</div>
125+
</div>
126+
```
127+
128+
**After** (correct):
129+
```html
130+
<div class="fd-select">
131+
<div class="fd-select__control" role="combobox" aria-expanded="false" aria-haspopup="listbox" tabindex="0">
132+
<span class="fd-select__text-content">Select an option</span>
133+
<span class="fd-button fd-button--transparent fd-select__button">
134+
<i class="sap-icon--slim-arrow-down" role="presentation"></i>
135+
</span>
136+
</div>
137+
</div>
138+
```
139+
140+
### Round 3 (2026-02-14 PM) - P2 Files Validation
141+
142+
#### 8. Fixed html-examples.json Navigation Shell
143+
144+
**Issue**: Wrong class names for side navigation component
145+
146+
**Before** (incorrect):
147+
```html
148+
<nav class="fd-side-nav">
149+
<div class="fd-side-nav__main-navigation">
150+
<ul class="fd-nested-list">
151+
<li class="fd-nested-list__item">
152+
<a class="fd-nested-list__link is-selected" href="#">
153+
<span class="sap-icon--home"></span>
154+
<span class="fd-nested-list__title">Home</span>
155+
</a>
156+
</li>
157+
</ul>
158+
</div>
159+
</nav>
160+
```
161+
162+
**After** (correct):
163+
```html
164+
<nav class="fd-side-nav" aria-roledescription="Main Navigation">
165+
<div class="fd-side-nav__container fd-side-nav__container--top">
166+
<ul class="fd-navigation-list level-1" role="tree" aria-roledescription="Navigation List Tree">
167+
<li class="fd-navigation-list__item" role="none">
168+
<a class="fd-navigation-list__content is-selected" role="treeitem" tabindex="0">
169+
<div class="fd-navigation-list__content-container">
170+
<span class="fd-navigation-list__icon">
171+
<i class="sap-icon--home" role="presentation"></i>
172+
</span>
173+
<span class="fd-navigation-list__text">Home</span>
174+
</div>
175+
</a>
176+
</li>
177+
</ul>
178+
</div>
179+
</nav>
180+
```
181+
60182
---
61183

62184
## Verification Results
@@ -67,7 +189,20 @@
67189
✅ All schemas: No trailing hyphen modifiers anywhere
68190
✅ utility-classes.json: Contains sap-has-shadow-color and sap-has-shadow-inverted-color
69191
✅ CLAUDE.md: Contains sap-flex--align-items-center
192+
✅ CLAUDE.md: Checkbox example matches packages/styles/stories/Components/Forms/checkbox/inline.example.html
193+
✅ CLAUDE.md: Radio example matches packages/styles/stories/Components/Forms/radio/primary.example.html
194+
✅ CLAUDE.md: Select example matches packages/styles/stories/Components/select/cozy.example.html
70195
✅ ai-component-index.md: Shows 120 components in all locations
196+
✅ component-catalog.json: 114 of 120 components have use cases (95%)
197+
198+
Round 3 - P2 Files:
199+
✅ design-tokens.json: 1,522 tokens extracted from @sap-theming/theming-base-content
200+
✅ modifier-rules.json: Button mutually exclusive modifiers verified against source SCSS
201+
✅ html-examples.json: Fixed navigation-shell to use fd-navigation-list classes
202+
✅ accessibility.json: 72 components with ARIA data verified against story files
203+
✅ icon-tab-bar roles (tab, tablist, tabpanel) verified against stories
204+
✅ button aria-pressed verified against stories
205+
✅ action-bar roles (menu, menuitem) verified against stories
71206
```
72207

73208
---
@@ -80,9 +215,37 @@
80215
| Utility classes | 227 | 229 (added missing) |
81216
| Hallucinated modifiers | 4 (fieldset) | 0 |
82217
| Incomplete modifiers | 8 (trailing `-`) | 0 |
218+
| HTML examples with errors | 4 | 0 |
219+
| Components with use cases | 20 | 114 |
220+
| Design tokens | N/A | 1,522 |
221+
| Components with accessibility | N/A | 72 |
222+
| Complete HTML patterns | N/A | 10 |
223+
224+
---
225+
226+
## Validation Method
227+
228+
All HTML examples in CLAUDE.md were cross-referenced against:
229+
1. Source SCSS files in `packages/styles/src/`
230+
2. Story HTML files in `packages/styles/stories/Components/`
231+
3. Component schemas in `docs/schemas/`
232+
233+
Button modifiers verified against `_button-types.scss`:
234+
- ✅ fd-button--emphasized
235+
- ✅ fd-button--positive
236+
- ✅ fd-button--negative
237+
- ✅ fd-button--transparent
238+
- ✅ fd-button--ghost
239+
- ✅ fd-button--compact
83240

84241
---
85242

86243
## Conclusion
87244

88-
All AI documentation artifacts are now accurate and verified against source code. The generator scripts have been fixed to prevent future hallucinations.
245+
All AI documentation artifacts are now accurate and verified against source code. The generator scripts have been fixed to prevent future hallucinations. HTML examples in CLAUDE.md and html-examples.json have been corrected to match actual component structures.
246+
247+
### P2 Files Added
248+
- **design-tokens.json**: 1,522 CSS custom properties extracted from SAP theming
249+
- **modifier-rules.json**: Mutually exclusive modifier rules for 8 components
250+
- **html-examples.json**: 10 complete HTML patterns for complex components
251+
- **accessibility.json**: ARIA patterns extracted from 72 components

0 commit comments

Comments
 (0)