Skip to content

chore: add ui-skills subagent for interface constraints #25

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 2 commits into from
Jan 10, 2026
Merged

chore: add ui-skills subagent for interface constraints #25

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ffb552
chore: add ui-skills subagent for interface constraints
marcusquinn Jan 10, 2026
069e70d
fix: postflight-check.sh now works with git worktrees
marcusquinn Jan 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agent/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,7 +246,7 @@ Subagents provide specialized capabilities. Read them when tasks require domain
| `tools/build-mcp/` | MCP development - creating Model Context Protocol servers and tools | build-mcp, api-wrapper, server-patterns, transports, deployment |
| `tools/ai-assistants/` | AI tool integration - configuring assistants, CAPTCHA solving, multi-modal agents | agno, capsolver, windsurf, configuration, status |
| `tools/browser/` | Browser automation - web scraping, testing, screenshots, form filling | stagehand, playwright, playwriter, crawl4ai, dev-browser, pagespeed, chrome-devtools |
| `tools/ui/` | UI components - component libraries, design systems | shadcn |
| `tools/ui/` | UI components - component libraries, design systems, interface constraints | shadcn, ui-skills |
| `tools/code-review/` | Code quality - linting, security scanning, style enforcement, PR reviews | code-standards, codacy, coderabbit, qlty, snyk, secretlint, auditing |
| `tools/context/` | Context optimization - semantic search, codebase indexing, token efficiency | osgrep, augment-context-engine, context-builder, context7, toon, dspy |
| `tools/conversion/` | Format conversion - document transformation between formats | pandoc |
Expand Down
31 changes: 25 additions & 6 deletions .agent/scripts/postflight-check.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ readonly NC='\033[0m'
# Repository info
readonly REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" || exit
readonly SONAR_PROJECT_KEY="marcusquinn_aidevops"
# Save the original working directory for git operations (supports worktrees)
readonly ORIGINAL_PWD="$PWD"

# Counters
PASSED=0
Expand Down Expand Up @@ -98,20 +100,37 @@ check_gh_cli() {
return 0
}

# Get repository owner and name
# Get repository owner and name from original directory (works with worktrees)
get_repo_info() {
local remote_url
remote_url=$(git -C "$REPO_ROOT" remote get-url origin 2>/dev/null || echo "")
# Use original working directory's git context (saved before cd to REPO_ROOT)
remote_url=$(git -C "$ORIGINAL_PWD" remote get-url origin 2>/dev/null || echo "")

if [[ -z "$remote_url" ]]; then
echo ""
return 1
fi

# Extract owner/repo from various URL formats
if [[ "$remote_url" =~ github\.com[:/]([^/]+)/([^/.]+) ]]; then
echo "${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
return 0
# Extract owner/repo from various URL formats using parameter expansion
# (bash 3.2 compatible - regex capture groups don't work reliably on macOS)
local repo_path
if [[ "$remote_url" == *"github.com"* ]]; then
# Handle HTTPS: https://github.com/owner/repo.git
if [[ "$remote_url" == *"github.com/"* ]]; then
repo_path="${remote_url#*github.com/}"
# Handle SSH: git@github.com:owner/repo.git
elif [[ "$remote_url" == *"github.com:"* ]]; then
repo_path="${remote_url#*github.com:}"
else
echo ""
return 1
fi
# Remove .git suffix if present
repo_path="${repo_path%.git}"
if [[ -n "$repo_path" && "$repo_path" == *"/"* ]]; then
echo "$repo_path"
return 0
fi
fi

echo ""
Expand Down
115 changes: 115 additions & 0 deletions .agent/tools/ui/ui-skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
description: Opinionated constraints for building better interfaces with agents
mode: subagent
tools:
read: true
write: true
edit: true
bash: true
glob: true
grep: true
webfetch: true
task: true
---

# UI Skills

<!-- AI-CONTEXT-START -->

## Quick Reference

- **Purpose**: Opinionated constraints for building better interfaces with agents
- **Source**: https://www.ui-skills.com/llms.txt
- **Stack**: Tailwind CSS, motion/react, tw-animate-css, clsx + tailwind-merge
Copy link

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with the Stack section below (line 46), it would be clearer to refer to the cn utility directly in the quick reference stack.

Suggested change
- **Stack**: Tailwind CSS, motion/react, tw-animate-css, clsx + tailwind-merge
- **Stack**: Tailwind CSS, motion/react, tw-animate-css, `cn` utility


**When to apply these constraints**:
- Building React/Next.js interfaces
- Working with Tailwind CSS
- Adding animations or transitions
- Creating accessible components
- Optimizing UI performance

**Key Principles**:
- Use Tailwind defaults before custom values
- Use accessible component primitives (Base UI, React Aria, Radix)
- Never add animation unless explicitly requested
- Respect `prefers-reduced-motion`
- Never block paste in inputs

<!-- AI-CONTEXT-END -->

## Stack

- MUST use Tailwind CSS defaults (spacing, radius, shadows) before custom values
- MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required
- SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS
- MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic

## Components

- MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`)
- MUST use the project's existing component primitives first
- NEVER mix primitive systems within the same interaction surface
- SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack
- MUST add an `aria-label` to icon-only buttons
- NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

## Interaction

- MUST use an `AlertDialog` for destructive or irreversible actions
- SHOULD use structural skeletons for loading states
- NEVER use `h-screen`, use `h-dvh`
- MUST respect `safe-area-inset` for fixed elements
- MUST show errors next to where the action happens
- NEVER block paste in `input` or `textarea` elements

## Animation

- NEVER add animation unless it is explicitly requested
- MUST animate only compositor props (`transform`, `opacity`)
- NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)
- SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)
- SHOULD use `ease-out` on entrance
- NEVER exceed `200ms` for interaction feedback
- MUST pause looping animations when off-screen
- MUST respect `prefers-reduced-motion`
- NEVER introduce custom easing curves unless explicitly requested
- SHOULD avoid animating large images or full-screen surfaces

## Typography

- MUST use `text-balance` for headings and `text-pretty` for body/paragraphs
- MUST use `tabular-nums` for data
- SHOULD use `truncate` or `line-clamp` for dense UI
- NEVER modify `letter-spacing` (`tracking-`) unless explicitly requested

## Layout

- MUST use a fixed `z-index` scale (no arbitrary `z-x`)
Copy link

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The placeholder z-x could be ambiguous. To make this instruction clearer for an agent, I suggest explicitly mentioning what an "arbitrary" value looks like in Tailwind CSS, such as the z-[value] syntax that should be avoided.

Suggested change
- MUST use a fixed `z-index` scale (no arbitrary `z-x`)
- MUST use a fixed `z-index` scale (e.g., `z-10`, `z-20`) and avoid arbitrary values (e.g., `z-[99]`)

- SHOULD use `size-x` for square elements instead of `w-x` + `h-x`
Copy link

@gemini-code-assist gemini-code-assist bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The use of x as a placeholder in size-x, w-x, and h-x might be unclear. Using a wildcard * would be more idiomatic and less ambiguous when describing Tailwind utility patterns.

Suggested change
- SHOULD use `size-x` for square elements instead of `w-x` + `h-x`
- SHOULD use `size-*` for square elements instead of `w-*` and `h-*`


## Performance

- NEVER animate large `blur()` or `backdrop-filter` surfaces
- NEVER apply `will-change` outside an active animation
- NEVER use `useEffect` for anything that can be expressed as render logic

## Design

- NEVER use gradients unless explicitly requested
- NEVER use purple or multicolor gradients
- NEVER use glow effects as primary affordances
- SHOULD use Tailwind CSS default shadow scale unless explicitly requested
- MUST give empty states one clear next action
- SHOULD limit accent color usage to one per view
- SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones

## Related Resources

- [UI Skills](https://www.ui-skills.com/)
- [Base UI](https://base-ui.com/react/components)
- [React Aria](https://react-spectrum.adobe.com/react-aria/)
- [Radix Primitives](https://www.radix-ui.com/primitives)
- [motion/react](https://motion.dev/)
- [tw-animate-css](https://github.com/Wombosvideo/tw-animate-css)
- [shadcn/ui](https://ui.shadcn.com/) - See `tools/ui/shadcn.md`