Skip to content

Commit 1e4823a

Browse files
hinzzxhinzzx
committed
docs: api pages framework used
1 parent 7ddca62 commit 1e4823a

1 file changed

Lines changed: 137 additions & 0 deletions

File tree

‎API_Pages_Framework.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Step-by-step framework on Team Balkan Components
2+
3+
Below is the exact framework that we used, to generate API Test Pages of Team Balkan's web components.
4+
5+
## Initial Setup and Prompt
6+
7+
### Initial Setup
8+
9+
- First we set-up a `components-list.instructions.md` file (we listed in a bulleted list all of the components Claude should iterate);
10+
- Secondly we created another file with all of the instructions from the ui5-webc-acc-hub (but a little tweaked), in our case it was named `acc-test-page-generation.instructions.md` (included in the Prompt below);
11+
12+
### Initial Prompt
13+
14+
#### We instruct the AI to FIRST generate one-or-two pages, just to make sure we're on the same page.
15+
16+
```prompt
17+
I need you to create a comprehensive API test page for ALL of the components listed in #file:components-list.instructions.md file.
18+
19+
Follow the instructions strictly. Let’s start with the first 2 components. Proceed step-by-step, following the instruction and be concise, DO NOT overengineer.
20+
Use #file:Avatar_ACC_APIs.html and #file:Avatar_ACC_Standards.html files as examples/refferences on how the pages are expected to be. You can also refer to the template provided in the #file:acc-test-page-generation.instructions.md .
21+
22+
Before implementing anything always double-consult with the instruction files. If uncertain for anything, better ask, instead of blindly making decisions. Proceed with the first two components.
23+
```
24+
25+
**Note:** Make sure to actually link the files in the prompt.
26+
27+
After that if the result were good, we instruct the Assistant to continue with the same patterns (we nailed it first try)
28+
29+
```prompt
30+
Perfect! Continue with all of the components listed in the #file:components-list.instructions.md file. The bar and the button are already implemented. As in the previous task, follow the instructions strictly. Proceed step-by-step, following the instructions and be concise, DO NOT overengineer.
31+
32+
Use the #file:Avatar_ACC_APIs.html , #file:Avatar_ACC_Standards.html , #file:Button_APIs.html files as examples, refferences. Refer to the template provided in the #file:acc-test-page-generation.instructions.md file. Before implementing anything, always double-check with the instruction files. if uncertain for ANYTHING ask, instead of blindly making decisions. Proceed with the remaining components.
33+
```
34+
35+
**Note**: Again, make sure to link the files in the prompt manually.
36+
37+
### Avoid hallucinations
38+
39+
A good practice to avoid hallucinations if you have components with large amount of lines, context or else, is to process the components in batches (we did it in batches of 6 to 10), depending on the complexity of the components.
40+
41+
So in short: every 6 to 10 components → New Chat → Prompt including something like:
42+
43+
```prompt
44+
I need you to create a comprehensive API test page for ALL of the REMAINING components listed in #file:components-list.instructions.md file.
45+
46+
Follow the instructions strictly. Proceed step-by-step, following the instruction and be concise, do not overengineer.
47+
Use #file:Bar_APIs.html, #file:Calendar_APIs.html, #file:ColorPalette_APIs.html and all of the attached files as examples/refferences on how the pages are expected to be. You can also refer to the template provided in the #file:acc-test-page-generation.instructions.md.
48+
49+
Before implementing anything always double-consult with the instruction files. If uncertain for anything, better ask, instead of blindly making decisions. Please proceed with ALL of the remaining components. You can split them in Batches to avoid token and context leakage. MAKE SURE TO NOT INCLUDE ANY DEPRECATED PROPERTIES AND TO INCLUDE ALL OF THE PROPERTIES (EXCEPT THE DEPRECATED ONES) in the test pages.
50+
```
51+
52+
### Error handling
53+
54+
As expected, not everything is always perfect from the first try, so we can encounter some errors, like imports, missing props and so on.
55+
56+
So a good way to handle errors (or at least from my experience) is to use semantic prompts. What I mean by that is structure your prompts, in a semantic way like emphasizing end/start of the error message, giving context or tips what could be the cause of the error, hints and so on. For example:
57+
58+
#### Error 1
59+
60+
Good! Unfortunately in the APIs page of the Date Components we are unable to see anything, and we've got the following error in the console:
61+
62+
```error
63+
LocaleData.ts:98 Uncaught (in promise) Error: CLDR data for locale en is not loaded!
64+
```
65+
66+
#### Error 2
67+
68+
We are still unable to see the components (the calendar). You can check the #file:Calendar.html file for hints, or #file:Calendar.ts for more insights on the CLDR.
69+
70+
```error
71+
LocaleData.ts:98 Uncaught (in promise) Error: CLDR data for locale en is not loaded!
72+
at getLocaleData (LocaleData.ts:98:9)
73+
at Object.loadResource (LoaderExtensions.ts:10:9)
74+
at getOrLoad (LocaleData.js:2520:55)
75+
at getData (LocaleData.js:2572:13)
76+
at new constructor (LocaleData.js:57:23)
77+
at new LocaleData (LocaleData.ts:6:1)
78+
at getCachedLocaleDataInstance (getCachedLocaleDataInstance.ts:9:21)
79+
at get _primaryCalendarType (DateComponentBase.ts:129:22)
80+
at Calendar.getFormat (DateComponentBase.ts:246:24)
81+
at get _selectedDatesTimestamps (Calendar.ts:355:56)
82+
```
83+
84+
## Manual AXE Testing
85+
86+
After all of the errors are handled, all APIs, samples and whatnot are here and our API Pages look good, we can now proceed to the acc part.
87+
88+
### What we did
89+
1. We manually traverse through our API pages and check for issues with the AXE tool
90+
2. All individual issues summarised and structured in Notes, .md file or else
91+
3. The file we did was structured in format like:
92+
93+
```md
94+
# Accessibility Issues Report
95+
96+
Files included in the report:
97+
98+
- Component X;
99+
- Component Y;
100+
- Component Z;
101+
102+
## Overview
103+
This document contains accessibility issues found across multiple API documentation pages.
104+
105+
## Component X
106+
107+
### Issues 1 of N (found with AXE)
108+
109+
**Element Location:**
110+
```code
111+
#element[class], .class[attr]
112+
```
113+
114+
**Element Code:**
115+
```html
116+
#element[class], .class[attr]
117+
```
118+
119+
**Problems**
120+
- Element does not have text that is visible to screen readers
121+
- aria-label attribute does not exist or is empty
122+
- aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
123+
- Element has no title attribute
124+
125+
**To solve this problem, you need to fix at least (1) of the following:**
126+
- Element does not have text that is visible to screen readers
127+
- aria-label attribute does not exist or is empty
128+
- aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
129+
- Element has no title attribute
130+
131+
**Issue Details:**
132+
- **Found:** Automatically
133+
- **Impact:** serious
134+
- **Categories:** cat.aria, wcag2a, wcag412, TTv5, TT6.a, EN-301-549, EN-9.4.1.2, ACT
135+
```
136+
4. Then we gave the document to the AI to fix the issues (if they were sample issues)
137+
5. Most (if not all) of them were component level ACC issues, at least in our case.

0 commit comments

Comments
 (0)