Practical guidance for developers and AI agents building interfaces that are easier to understand, use, , resume and correct.
Version: v1.01 · Updated October 19, 2026
What is this? · Use it · Install it · What else?
- Guide: Rules for making context, relationships, actions and recovery understandable. Use it to design or review an interface, with or without AI.
- Skill: A workflow for AI development agents: understand your codebase, apply the Guide and verify improvements.
- Examples: Anannotated screenshot gallery , worked patterns,runnable React and Svelte interfaces , and22 skins with chart palettes . Explore the choices, see the rules in action and adapt useful patterns to your own stack.
Select or name the audhd-ui-guide skill, then choose a prompt below. Paste prompts into your agent’s chat:
- Review an existing interface: “Use the audhd-ui-guide skill. Run an AuDHD audit on this program's UI components. Report the main problems and recommended improvements before changing anything.”
- Build a configuration dashboard: “Use the audhd-ui-guide skill. Here are my configuration files and codebase. Build an AuDHD-friendly settings dashboard using the real defaults, dependencies and save behavior.”
- Add a front end: “Use the audhd-ui-guide skill. Add an AuDHD-friendly front end to this codebase. Use the existing stack, preserve behavior and permissions, and verify complete workflows.”
- Improve a specific difficulty: “Use the audhd-ui-guide skill. Make the selected item and its detail panel clearly connected. Preserve drafts, navigation and keyboard focus, and explain what you verified.”
Start with one task; you do not need to redesign everything. For a manual review, follow Try one small review. For agents without skill discovery, use the attachment-based instructions.
Choose one platform and one scope: personal installation makes the skill available across your projects; project installation makes it available inside one application project. ~ means your home directory; paths without ~ start at the application project.
Download with Git: This creates anaudhd-ui-guide folder inside your current directory. You can run it from your chosen skills directory to install there directly:
git clone https://github.com/Greyland-Fireworks/audhd-ui-guide.git
Codex: Put the folder at~/.agents/skills/audhd-ui-guide/ for personal use across projects, or.agents/skills/audhd-ui-guide/ inside the project being worked on. SeeCodex skill locations . #
Claude Code: Use~/.claude/skills/audhd-ui-guide/ for personal use or.claude/skills/audhd-ui-guide/ inside a project. SeeClaude Code skill locations . #
Cursor: Use~/.cursor/skills/audhd-ui-guide/ for personal use or.cursor/skills/audhd-ui-guide/ inside a project. Cursor also supports the.agents/skills/ locations used by Codex; choose one location rather than installing duplicate copies. SeeCursor skill locations . #
Keep the supporting files together: KeepSKILL.md ,GUIDE.md and the other public files in their original relative locations. Exclude ignored research, personal profiles, dependencies and build/test output when copying a working checkout. #
Confirm it is available: Open the application project in your agent and select or nameaudhd-ui-guide . Check the skill selector; refresh or restart the agent if needed. Local installation does not automatically install the skill in a remote or cloud environment—follow that platform's setup instructions there.
Reading the Guide and using the Skill require no npm installation. Run the examples only if you want to explore the demonstrations.
Installation details: empty folders, Windows, WSL and verification limits #
To clone directly into your current empty directory, name that directory audhd-ui-guide and run:
git clone https://github.com/Greyland-Fireworks/audhd-ui-guide.git .
On Windows, use the corresponding folders under your user home or project. For an agent running in WSL, use its Linux environment's folders.
The platform links above document the installation locations. This project has not tested end-to-end skill installation in each platform.
- Personal choice matters: Accessible behavior is mandatory; light/dark skins, typography and enjoyable visual variety are selectable. No single appearance suits everyone. Seepersonalization .
- You can set priorities: Chooseprimary targets and rule emphasis to focus the work without weakening accessibility, authorization or correct behavior.
- Audits start with findings: An audit reviews the interface. Ask explicitly when you want implementation; ordinary use does not authorize publishing, changing permissions or storing personal preferences.
- The examples have clear limits: Demo reviews stay in memory and reset on reload. Export downloads preferences only. Keep personal preference files private; seethe preference contract .
- Evidence has boundaries: Automated reference checks have passed; actual browser zoom, screen-reader operation and participant evaluation remain pending. This practitioner guidance is not a clinical intervention or accessibility certification. Seethe acceptance record .
- Reuse and feedback are welcome: Code and CSS use MIT; documentation uses CC BY 4.0, with separate logo terms. Seelicensing ,contribution guidance and thecommunity .
Choose the next task that matters to you:
- Try it:Run the examples orreview one small workflow .
- Adapt it:Use with an LLM ,personalize the interface orbrowse the resource directory .
- Understand the project:Background ,accessibility ,community andlicensing .
| I want to… | Open this |
|---|---|
| Understand the rules and visual treatment | Combined guide |
| Understand UI versus UX and where each is covered | Project definitions |
| Organize a dashboard with clear priorities and navigation | Dashboard organization |
| Group related tools and settings into tabs or expandable sections | Tabs, sub-tabs and accordion sections |
| Tailor colors, text, density, motion or interruption support | Personalization overview andJSON reference |
| Check an existing interface | Review template |
| See context, help and recovery in practice | Worked examples |
| Use the guide with an LLM | Usage instructions andagent skill |
| Evaluate an LLM's use of the guide | Skill evaluation pack |
| Suggest a change or share evidence | Contribution guidance |
| Ask a question or discuss an example | Discord community |
Recording-review setup · Palette preview and tokens · Framework adapters · Evidence and limits
These are local demonstrations. Reviews reset on reload; export downloads preferences only.
With Node 22.12+ installed, open a terminal in the repository root—the folder containing package.json—and install dependencies once:
npm ci
React: Start the server, then open the React example:
npm run dev:react
Svelte: In a separate terminal at the same repository root, start the server and open the Svelte example:
npm run dev:svelte
You can run either example independently. If a port is already in use, follow the alternate-port instructions. To explore palettes without starting either app, open the palette preview in your browser.
| Resource | Status and limits |
|---|---|
| React recording review | Implemented with provisional React Aria; independent state logic |
| Svelte 5 recording review | Implemented with provisional Bits UI; independent state logic |
| Skins and text styles | 22 named skins, 11 light/11 dark, four text styles; Guillermo is an example default |
| Preference version 2 | Schemas, strict validation, explicit migration, local preview/application/export; bounded supported fields |
| Angular and Vue | Adapter documentation; full implementations and executable verification Pending |
| Verification | Acceptance record separates runtime results from pending zoom, screen-reader and participant checks |
- Choose a real task. For example: edit a setting, save it, leave and return.
- Follow the task from beginning to end. Include a mistake or failed save where you can test safely.
- Write down what happened. Use thereview template , select the relevant rule IDs and identify one focused improvement.
Keep these questions nearby:
- Can I tell what I am editing and what the change affects?
- Can I see what is selected, what is taking effect and whether it saved?
- Can I recover a mistake without starting over?
- Can I return after an interruption and find my place?
- Can I operate the interface without relying on color, hover or a mouse alone?
Follow How do I install it? for download commands, platform locations and discovery checks.
Open the project you want reviewed and name the screen or workflow. Provide relevant source files, screenshots or an accessible running interface as available. Explain the task users need to complete, any known difficulty and whether you want review, design or implementation.
Skill installation and explicit invocation syntax vary by tool. You can name the skill in your request:
Use the audhd-ui-guide skill to review the report settings form. Focus on changing the destination, saving, recovering a failed save and returning later. Review only.
Once the skill is available to the agent, type audhd audit as a request. The phrase is case-insensitive and is an instruction recognized by this skill, not a shell command or a separately installed slash command. If your agent does not discover it automatically, explicitly select or name audhd-ui-guide with the request.
| Request | Scope |
|---|---|
audhd audit |
The interface, change or task already under discussion; asks for a target if none can be identified |
audhd audit the publishing dashboard |
Dashboard hierarchy, metrics, alerts, navigation and the relevant task behavior |
audhd audit the settings form, especially failed saves and returning after an interruption |
The named form and workflow, with emphasis on recovery and continuity |
The audit is review-only by default. Expect prioritized findings that distinguish UI, UX or both, identify relevant rule IDs and evidence, and recommend focused changes and verification steps. Checks that cannot be performed remain pending. A screenshot can support visible-layout findings but cannot prove save behavior, keyboard access or user understanding. No findings is a valid outcome when the available evidence justifies no change; remaining evidence gaps must still be reported.
The trigger does not request a whole-project redesign, theme migration or model evaluation. To authorize implementation, say so explicitly and bound the change:
Use the audhd-ui-guide skill. Audit the settings form, then fix misleading save feedback and inaccessible help. Preserve existing permissions and saved work; report the changes, actual checks and remaining gaps.
Use the opening prompts to request a dashboard, front end or focused improvement. Include the relevant files, intended task and any project constraints. An audit is optional.
Ask the agent to distinguish verified behavior from unknowns, preserve existing permissions and saved work, and report checks actually performed. A focused change does not authorize a whole-application redesign.
Attach SKILL.md, GUIDE.md and REVIEW_TEMPLATE.md to the conversation and use this prompt:
Apply the attached AuDHD-friendly interface guide to [interface and task]. Follow the skill instructions, including selectable appearance, task continuity and system accessibility constraints. Stay within this task and preserve existing behavior and saved work. Distinguish UI and UX concerns; report relevant rule IDs, evidence, checks performed and remaining gaps. Review only unless I ask you to implement changes.
Attach EXAMPLES.md when examples would help. For personalization work, also attach PREFERENCES.md and preferences.example.json; the JSON is a fictional reference, not a personal profile.
For individual design or personalization, the skill offers a brief, optional intake about display and interaction needs. Answer only what matters, try a preview or skip the questions. A diagnosis is never required. For products serving many people, one person's preferences do not represent every user.
Options include color plus labels/shapes/patterns, text size and spacing, density, motion, sound, optional notifications, help detail and interruption recovery. The preference guidance explains the questions, storage rules and supported profile format.
To request a temporary adjustment:
Use larger text and no optional sounds for this task. Skip the other preference questions and do not save a profile.
To remember confirmed choices:
Save the text scale and sound preference we just agreed on for this project in audhd-preferences.local.json. Keep my other saved choices unchanged.
Saving a preference does not implement or verify it. The example JSON illustrates the format; the JSON field reference explains every option. Unsupported preferences must be reported. System accessibility overrides and privacy requirements remain in effect.
Area for improvement: Intake, profile handling and preference effects need real-user and integration testing. See the documented follow-up.
AuDHD commonly refers to the co-occurrence of autism and ADHD. Some people want a focused view; others need a dense overview. Offer useful choices and test them with the people doing the work. You do not need to disclose a diagnosis to contribute.
This is a practitioner guide, not a clinical intervention or certification. Its specific patterns have not been established here through research with a representative group of AuDHD users. No skin, font or information density is claimed to suit every AuDHD person.
Version v1.01 is being prepared for publication. The Guide remains practitioner guidance with the evidence limits described above. All 34 prepared model-evaluation scenarios remain unrun and require a separate explicit request. Those evaluations are not required for ordinary use or feedback, and successful text reviews would not prove real-interface usability.
Note
Why I developed this guide
Despite the serious concerns about the social and ecological impacts of AI/ML, working with Large Language Models to develop software has been life-changing for me.
Throughout my life, I tried several times to learn programming. But the way my AuDHD brain works made it difficult to retain and recall the information I needed in the moment to write code manually.
The only languages I was ever able to work with were HTML and Terrapin Logo. I knew a great deal about computers and technology, even built huge interactive art projects for hacker conferences, but I always felt shut out of the driver’s seat, and making a computer do exactly what I wanted it to do.
Over the last two years, I’ve built project after project using LLMs as coding assistants. Along the way, I developed many tools to help me do more. I created parts of this guide to help keep the interfaces they build organized and understandable to me, particularly backend dashboards. Due to the AuDHD memory constraints, I needed those interfaces customized to make sense when I frequently couldn’t remember how or why I had built certain features.
I’m publishing this guide in the hope that it helps someone facing similar difficulties. Please join me on the Discord server to connect with other AuDHD software creators.
— Charles Beckwith, @fashiontechguru
For web work, use WCAG 2.2 as the formal accessibility reference, with Level AA as a baseline. W3C cognitive accessibility guidance provides additional usability guidance. For native applications, use the platform's accessibility guidance and assistive technologies.
This guide supplements those resources. It does not replace a conformance evaluation. Report specific findings such as “Keyboard recovery tested in this build,” rather than “AuDHD compliant.”
Preserve existing product behavior, permissions, privacy and saved work when improving presentation. A collapsed panel is a view preference; approving or publishing content is a separate action.
Join the Discord community to ask questions, share interface examples and discuss improvements.
For a structured proposal, include the task, relevant rule ID, what happened and what you would change. The contribution guidance explains how to share useful evidence without exposing private information.
The JSON preference reference explains every field in preferences.example.json, including value types, example values, inheritance and privacy. These preferences describe requested behavior; applications and agents must implement and verify supported settings. See PREFERENCES.md for intake and storage guidance.
- Code, CSS, schemas and tooling:MIT .
- Guide, Skill, documentation and fictional preference examples:CC BY 4.0 .
- Third-party dependencies: Their upstream licenses apply. See thefull license scope and attribution .
Logo: You may display the unmodified logo to identify, discuss or link to this project, with credit and a link to the project. Other uses, including unrelated product branding or merchandise, require prior written permission. Permission does not imply endorsement.
Project origin and version history #
This standalone guide combines 13 interaction rules and a visual standard, with adaptable light/dark appearances, for use across projects.
This repository includes the license scope and attribution and contribution terms. This practitioner draft retains the evidence limits described above.
v1.01 — October 19, 2026: Accessible selectable appearance, connected context/navigation/help, portable v2 preferences, React/Svelte references, chart skins and explicit adapter/evidence boundaries. Profile schema version 2 is not a Guide release number. #
1.01 draft — October 18, 2026: Strengthened contextual help and visible relationships; added explicit priority hierarchy, configurable rule emphasis and primary targets, with matching Skill instructions and examples. Existing requirements and version-1 JSON profiles remain intact. #
1.0 draft — October 17, 2026: Combined project-independent guide, mandatory dark theme, contribution guidance and reusable review template. README includes project artwork, direct task links and a short review checklist.