ai-friendly-web-design

Name: ai-friendly-web-design
Author: ianho7

70stars2forks

How to install ai-friendly-web-design?

ianho7/ai-friendly-web-design-skill/ai-friendly-web-design

$npx -y skills add ianho7/ai-friendly-web-design-skill --skill ai-friendly-web-design

Installs into the current project.

Summary

Build, review, and refactor web interfaces that are easy for humans, screen readers, browser automation, Playwright tests, and AI agents to understand and operate. Use for UI components, forms, frontend features, semantic HTML, ARIA, stable locators, URL state, accessibility revi

Files · 1

View on GitHub

SKILL.md

1	# AI-Friendly Web Design
2
3	## Purpose
4
5	Use this skill to make web interfaces easier to discover, operate, test, and review across human users, assistive technology, browser automation, and AI agents.
6
7	## When To Use
8
9	Use this skill when the task involves any of the following:
10
11	- Designing a new UI flow, screen, component, or form
12	- Implementing or refactoring frontend UI
13	- Reviewing existing UI for accessibility, automation, or operability issues
14	- Writing Playwright or browser automation tests
15	- Deciding semantic HTML, ARIA, locator, or URL state patterns
16
17	## Task Modes
18
19	Choose one primary mode before acting.
20
21	### 1. Design New UI
22
23	- List the core user tasks before proposing components.
24	- Define the UI contract in user-facing terms: actions, fields, states, and outcomes.
25	- Cover loading, error, empty, and success states explicitly.
26	- Decide which state should be reproducible through the URL.
27	- Mark which critical controls need stable locators.
28
29	### 2. Implement UI
30
31	- Prefer native HTML elements before custom widgets.
32	- Add ARIA only when native semantics are not enough.
33	- Ensure every critical control has an accessible name.
34	- Keep critical state readable as visible or programmatically associated text.
35	- Add stable locator hooks only for critical actions, fields, and status.
36
37	### 3. Review Existing UI
38
39	- Output findings as High, Medium, and Low severity.
40	- Prefer the display format `🔴 High`, `🟡 Medium`, and `🟢 Low` when the output surface supports emoji.
41	- Explain how each issue affects accessibility, automation, or agent operability.
42	- Prioritize blockers on critical user flows.
43	- Give concrete fixes instead of abstract advice.
44	- If a suggested fix would change hover, click, close, focus, expand, or layout behavior, present it as a behavior-change proposal requiring confirmation rather than a direct recommendation.
45	- Avoid unrelated redesign or architecture churn.
46
47	### 4. Refactor Existing UI
48
49	- Prefer the smallest patch that fixes operability.
50	- Preserve the current visual design unless the user asked for redesign.
51	- Preserve existing interaction paths and visible layout by default, including hover, click, outside-click-close, blank-area-close, Esc-close, expand/collapse, and focus return, unless the user explicitly approves a behavior change.
52	- Preserve the existing design system and component boundaries where practical.
53	- Fix the parts that break semantics, state clarity, or stable interaction.
54	- Do not use this work as an excuse to rewrite the stack.
55
56	### 5. Generate Tests
57
58	- Prefer user-facing locators such as role, label, and text.
59	- Avoid CSS selectors unless there is no stable user-facing alternative.
60	- Cover critical flows plus loading, error, and success states.
61	- Use stable custom locators only when the UI needs them.
62	- Write tests around observable behavior, not implementation details.
63
64	## Non-Negotiables
65
66	- Use semantic HTML before ARIA.
67	- Prefer native browser controls before custom widgets.
68	- Critical actions must not be hover-only.
69	- Critical flows must not depend on popup-only, drag-only, or canvas-only interaction.
70	- Every critical control needs an accessible name.
71	- Loading, error, empty, and success states must be readable text.
72	- Critical actions and fields need stable ways to locate them.
73	- Search, filter, sort, pagination, and selected tab state should usually be reflected in the URL.
74	- Do not add CAPTCHA, agent manifests, or automation-specific APIs unless the user asks or the project already needs them.
75
76	## Reference Routing
77
78	Read only the files needed for the current task.
79
80	- For core goals, severity, and review judgment: `references/principles.md`
81	- For semantic HTML, native control choices, and interaction anti-patterns: `references/semantic-html-first.md`
82	- For stable locators and URL state: `references/locator-and-state.md`
83	- For review deliverables and AI-readable content notes: `references/review-output-format.md`
84	- For quick implementation or review guidance on common components: `references/component-recipes.md`
85
86	## Output Rules
87
88	- State the chosen task mode before substantial action when the mode is not obvious from context.
89	- Keep recommendations tied to critical user tasks and observable UI behavior.
90	- When reviewing, use the review format in `references/review-output-format.md`.
91	- When reviewing, use severity labels `🔴 High`, `🟡 Medium`, and `🟢 Low` when possible. If emoji rendering is unavailable, use `High`, `Medium`, and `Low` exactly.
92	- When implementing or refactoring, explain any non-native control choice and why native HTML was not sufficient.
93	- When adding custom locators, keep naming stable and

People who liked this also viewed

6 picks

Type

ai-friendly-web-design

70stars2forks

View on GitHub

How to install ai-friendly-web-design?

ianho7/ai-friendly-web-design-skill/ai-friendly-web-design

$npx -y skills add ianho7/ai-friendly-web-design-skill --skill ai-friendly-web-design

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# AI-Friendly Web Design
2
3	## Purpose
4
5	Use this skill to make web interfaces easier to discover, operate, test, and review across human users, assistive technology, browser automation, and AI agents.
6
7	## When To Use
8
9	Use this skill when the task involves any of the following:
10
11	- Designing a new UI flow, screen, component, or form
12	- Implementing or refactoring frontend UI
13	- Reviewing existing UI for accessibility, automation, or operability issues
14	- Writing Playwright or browser automation tests
15	- Deciding semantic HTML, ARIA, locator, or URL state patterns
16
17	## Task Modes
18
19	Choose one primary mode before acting.
20
21	### 1. Design New UI
22
23	- List the core user tasks before proposing components.
24	- Define the UI contract in user-facing terms: actions, fields, states, and outcomes.
25	- Cover loading, error, empty, and success states explicitly.
26	- Decide which state should be reproducible through the URL.
27	- Mark which critical controls need stable locators.
28
29	### 2. Implement UI
30
31	- Prefer native HTML elements before custom widgets.
32	- Add ARIA only when native semantics are not enough.
33	- Ensure every critical control has an accessible name.
34	- Keep critical state readable as visible or programmatically associated text.
35	- Add stable locator hooks only for critical actions, fields, and status.
36
37	### 3. Review Existing UI
38
39	- Output findings as High, Medium, and Low severity.
40	- Prefer the display format `🔴 High`, `🟡 Medium`, and `🟢 Low` when the output surface supports emoji.
41	- Explain how each issue affects accessibility, automation, or agent operability.
42	- Prioritize blockers on critical user flows.
43	- Give concrete fixes instead of abstract advice.
44	- If a suggested fix would change hover, click, close, focus, expand, or layout behavior, present it as a behavior-change proposal requiring confirmation rather than a direct recommendation.
45	- Avoid unrelated redesign or architecture churn.
46
47	### 4. Refactor Existing UI
48
49	- Prefer the smallest patch that fixes operability.
50	- Preserve the current visual design unless the user asked for redesign.
51	- Preserve existing interaction paths and visible layout by default, including hover, click, outside-click-close, blank-area-close, Esc-close, expand/collapse, and focus return, unless the user explicitly approves a behavior change.
52	- Preserve the existing design system and component boundaries where practical.
53	- Fix the parts that break semantics, state clarity, or stable interaction.
54	- Do not use this work as an excuse to rewrite the stack.
55
56	### 5. Generate Tests
57
58	- Prefer user-facing locators such as role, label, and text.
59	- Avoid CSS selectors unless there is no stable user-facing alternative.
60	- Cover critical flows plus loading, error, and success states.
61	- Use stable custom locators only when the UI needs them.
62	- Write tests around observable behavior, not implementation details.
63
64	## Non-Negotiables
65
66	- Use semantic HTML before ARIA.
67	- Prefer native browser controls before custom widgets.
68	- Critical actions must not be hover-only.
69	- Critical flows must not depend on popup-only, drag-only, or canvas-only interaction.
70	- Every critical control needs an accessible name.
71	- Loading, error, empty, and success states must be readable text.
72	- Critical actions and fields need stable ways to locate them.
73	- Search, filter, sort, pagination, and selected tab state should usually be reflected in the URL.
74	- Do not add CAPTCHA, agent manifests, or automation-specific APIs unless the user asks or the project already needs them.
75
76	## Reference Routing
77
78	Read only the files needed for the current task.
79
80	- For core goals, severity, and review judgment: `references/principles.md`
81	- For semantic HTML, native control choices, and interaction anti-patterns: `references/semantic-html-first.md`
82	- For stable locators and URL state: `references/locator-and-state.md`
83	- For review deliverables and AI-readable content notes: `references/review-output-format.md`
84	- For quick implementation or review guidance on common components: `references/component-recipes.md`
85
86	## Output Rules
87
88	- State the chosen task mode before substantial action when the mode is not obvious from context.
89	- Keep recommendations tied to critical user tasks and observable UI behavior.
90	- When reviewing, use the review format in `references/review-output-format.md`.
91	- When reviewing, use severity labels `🔴 High`, `🟡 Medium`, and `🟢 Low` when possible. If emoji rendering is unavailable, use `High`, `Medium`, and `Low` exactly.
92	- When implementing or refactoring, explain any non-native control choice and why native HTML was not sufficient.
93	- When adding custom locators, keep naming stable and

People who liked this also viewed

6 picks

Type