csh
3d83740f88
25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
11 KiB
11 KiB
| 1 | No | Category | Guideline | Description | Do | Don't | Code Good | Code Bad | Severity | Docs URL |
|---|---|---|---|---|---|---|---|---|---|---|
| 2 | 1 | Animation | Use Tailwind animate utilities | Built-in animations are optimized and respect reduced-motion | Use animate-pulse animate-spin animate-ping | Custom @keyframes for simple effects | animate-pulse | @keyframes pulse {...} | Medium | https://tailwindcss.com/docs/animation |
| 3 | 2 | Animation | Limit bounce animations | Continuous bounce is distracting and causes motion sickness | Use animate-bounce sparingly on CTAs only | Multiple bounce animations on page | Single CTA with animate-bounce | 5+ elements with animate-bounce | High | |
| 4 | 3 | Animation | Transition duration | Use appropriate transition speeds for UI feedback | duration-150 to duration-300 for UI | duration-1000 or longer for UI elements | transition-all duration-200 | transition-all duration-1000 | Medium | https://tailwindcss.com/docs/transition-duration |
| 5 | 4 | Animation | Hover transitions | Add smooth transitions on hover state changes | Add transition class with hover states | Instant hover changes without transition | hover:bg-gray-100 transition-colors | hover:bg-gray-100 (no transition) | Low | |
| 6 | 5 | Z-Index | Use Tailwind z-* scale | Consistent stacking context with predefined scale | z-0 z-10 z-20 z-30 z-40 z-50 | Arbitrary z-index values | z-50 for modals | z-[9999] | Medium | https://tailwindcss.com/docs/z-index |
| 7 | 6 | Z-Index | Fixed elements z-index | Fixed navigation and modals need explicit z-index | z-50 for nav z-40 for dropdowns | Relying on DOM order for stacking | fixed top-0 z-50 | fixed top-0 (no z-index) | High | |
| 8 | 7 | Z-Index | Negative z-index for backgrounds | Use negative z-index for decorative backgrounds | z-[-1] for background elements | Positive z-index for backgrounds | -z-10 for decorative | z-10 for background | Low | |
| 9 | 8 | Layout | Container max-width | Limit content width for readability | max-w-7xl mx-auto for main content | Full-width content on large screens | max-w-7xl mx-auto px-4 | w-full (no max-width) | Medium | https://tailwindcss.com/docs/container |
| 10 | 9 | Layout | Responsive padding | Adjust padding for different screen sizes | px-4 md:px-6 lg:px-8 | Same padding all sizes | px-4 sm:px-6 lg:px-8 | px-8 (same all sizes) | Medium | |
| 11 | 10 | Layout | Grid gaps | Use consistent gap utilities for spacing | gap-4 gap-6 gap-8 | Margins on individual items | grid gap-6 | grid with mb-4 on each item | Medium | https://tailwindcss.com/docs/gap |
| 12 | 11 | Layout | Flexbox alignment | Use flex utilities for alignment | items-center justify-between | Multiple nested wrappers | flex items-center justify-between | Nested divs for alignment | Low | |
| 13 | 12 | Images | Aspect ratio | Maintain consistent image aspect ratios | aspect-video aspect-square | No aspect ratio on containers | aspect-video rounded-lg | No aspect control | Medium | https://tailwindcss.com/docs/aspect-ratio |
| 14 | 13 | Images | Object fit | Control image scaling within containers | object-cover object-contain | Stretched distorted images | object-cover w-full h-full | No object-fit | Medium | https://tailwindcss.com/docs/object-fit |
| 15 | 14 | Images | Lazy loading | Defer loading of off-screen images | loading='lazy' on images | All images eager load | <img loading='lazy'> | <img> without lazy | High | |
| 16 | 15 | Images | Responsive images | Serve appropriate image sizes | srcset and sizes attributes | Same large image all devices | srcset with multiple sizes | 4000px image everywhere | High | |
| 17 | 16 | Typography | Prose plugin | Use @tailwindcss/typography for rich text | prose prose-lg for article content | Custom styles for markdown | prose prose-lg max-w-none | Custom text styling | Medium | https://tailwindcss.com/docs/typography-plugin |
| 18 | 17 | Typography | Line height | Use appropriate line height for readability | leading-relaxed for body text | Default tight line height | leading-relaxed (1.625) | leading-none or leading-tight | Medium | https://tailwindcss.com/docs/line-height |
| 19 | 18 | Typography | Font size scale | Use consistent text size scale | text-sm text-base text-lg text-xl | Arbitrary font sizes | text-lg | text-[17px] | Low | https://tailwindcss.com/docs/font-size |
| 20 | 19 | Typography | Text truncation | Handle long text gracefully | truncate or line-clamp-* | Overflow breaking layout | line-clamp-2 | No overflow handling | Medium | https://tailwindcss.com/docs/text-overflow |
| 21 | 20 | Colors | Opacity utilities | Use color opacity utilities | bg-black/50 text-white/80 | Separate opacity class | bg-black/50 | bg-black opacity-50 | Low | https://tailwindcss.com/docs/background-color |
| 22 | 21 | Colors | Dark mode | Support dark mode with dark: prefix | dark:bg-gray-900 dark:text-white | No dark mode support | dark:bg-gray-900 | Only light theme | Medium | https://tailwindcss.com/docs/dark-mode |
| 23 | 22 | Colors | Semantic colors | Use semantic color naming in config | primary secondary danger success | Generic color names in components | bg-primary | bg-blue-500 everywhere | Medium | |
| 24 | 23 | Spacing | Consistent spacing scale | Use Tailwind spacing scale consistently | p-4 m-6 gap-8 | Arbitrary pixel values | p-4 (1rem) | p-[15px] | Low | https://tailwindcss.com/docs/customizing-spacing |
| 25 | 24 | Spacing | Negative margins | Use sparingly for overlapping effects | -mt-4 for overlapping elements | Negative margins for layout fixing | -mt-8 for card overlap | -m-2 to fix spacing issues | Medium | |
| 26 | 25 | Spacing | Space between | Use space-y-* for vertical lists | space-y-4 on flex/grid column | Margin on each child | space-y-4 | Each child has mb-4 | Low | https://tailwindcss.com/docs/space |
| 27 | 26 | Forms | Focus states | Always show focus indicators | focus:ring-2 focus:ring-blue-500 | Remove focus outline | focus:ring-2 focus:ring-offset-2 | focus:outline-none (no replacement) | High | |
| 28 | 27 | Forms | Input sizing | Consistent input dimensions | h-10 px-3 for inputs | Inconsistent input heights | h-10 w-full px-3 | Various heights per input | Medium | |
| 29 | 28 | Forms | Disabled states | Clear disabled styling | disabled:opacity-50 disabled:cursor-not-allowed | No disabled indication | disabled:opacity-50 | Same style as enabled | Medium | |
| 30 | 29 | Forms | Placeholder styling | Style placeholder text appropriately | placeholder:text-gray-400 | Dark placeholder text | placeholder:text-gray-400 | Default dark placeholder | Low | |
| 31 | 30 | Responsive | Mobile-first approach | Start with mobile styles and add breakpoints | Default mobile + md: lg: xl: | Desktop-first approach | text-sm md:text-base | text-base max-md:text-sm | Medium | https://tailwindcss.com/docs/responsive-design |
| 32 | 31 | Responsive | Breakpoint testing | Test at standard breakpoints | 320 375 768 1024 1280 1536 | Only test on development device | Test all breakpoints | Single device testing | High | |
| 33 | 32 | Responsive | Hidden/shown utilities | Control visibility per breakpoint | hidden md:block | Different content per breakpoint | hidden md:flex | Separate mobile/desktop components | Low | https://tailwindcss.com/docs/display |
| 34 | 33 | Buttons | Button sizing | Consistent button dimensions | px-4 py-2 or px-6 py-3 | Inconsistent button sizes | px-4 py-2 text-sm | Various padding per button | Medium | |
| 35 | 34 | Buttons | Touch targets | Minimum 44px touch target on mobile | min-h-[44px] on mobile | Small buttons on mobile | min-h-[44px] min-w-[44px] | h-8 w-8 on mobile | High | |
| 36 | 35 | Buttons | Loading states | Show loading feedback | disabled + spinner icon | Clickable during loading | <Button disabled><Spinner/></Button> | Button without loading state | High | |
| 37 | 36 | Buttons | Icon buttons | Accessible icon-only buttons | aria-label on icon buttons | Icon button without label | <button aria-label='Close'><XIcon/></button> | <button><XIcon/></button> | High | |
| 38 | 37 | Cards | Card structure | Consistent card styling | rounded-lg shadow-md p-6 | Inconsistent card styles | rounded-2xl shadow-lg p-6 | Mixed card styling | Low | |
| 39 | 38 | Cards | Card hover states | Interactive cards should have hover feedback | hover:shadow-lg transition-shadow | No hover on clickable cards | hover:shadow-xl transition-shadow | Static cards that are clickable | Medium | |
| 40 | 39 | Cards | Card spacing | Consistent internal card spacing | space-y-4 for card content | Inconsistent internal spacing | space-y-4 or p-6 | Mixed mb-2 mb-4 mb-6 | Low | |
| 41 | 40 | Accessibility | Screen reader text | Provide context for screen readers | sr-only for hidden labels | Missing context for icons | <span class='sr-only'>Close menu</span> | No label for icon button | High | https://tailwindcss.com/docs/screen-readers |
| 42 | 41 | Accessibility | Focus visible | Show focus only for keyboard users | focus-visible:ring-2 | Focus on all interactions | focus-visible:ring-2 | focus:ring-2 (shows on click too) | Medium | |
| 43 | 42 | Accessibility | Reduced motion | Respect user motion preferences | motion-reduce:animate-none | Ignore motion preferences | motion-reduce:transition-none | No reduced motion support | High | https://tailwindcss.com/docs/hover-focus-and-other-states#prefers-reduced-motion |
| 44 | 43 | Performance | Configure content paths | Tailwind needs to know where classes are used | Use 'content' array in config | Use deprecated 'purge' option (v2) | content: ['./src/**/*.{js,ts,jsx,tsx}'] | purge: [...] | High | https://tailwindcss.com/docs/content-configuration |
| 45 | 44 | Performance | JIT mode | Use JIT for faster builds and smaller bundles | JIT enabled (default in v3) | Full CSS in development | Tailwind v3 defaults | Tailwind v2 without JIT | Medium | |
| 46 | 45 | Performance | Avoid @apply bloat | Use @apply sparingly | Direct utilities in HTML | Heavy @apply usage | class='px-4 py-2 rounded' | @apply px-4 py-2 rounded; | Low | https://tailwindcss.com/docs/reusing-styles |
| 47 | 46 | Plugins | Official plugins | Use official Tailwind plugins | @tailwindcss/forms typography aspect-ratio | Custom implementations | @tailwindcss/forms | Custom form reset CSS | Medium | https://tailwindcss.com/docs/plugins |
| 48 | 47 | Plugins | Custom utilities | Create utilities for repeated patterns | Custom utility in config | Repeated arbitrary values | Custom shadow utility | shadow-[0_4px_20px_rgba(0,0,0,0.1)] everywhere | Medium | |
| 49 | 48 | Layout | Container Queries | Use @container for component-based responsiveness | Use @container and @lg: etc. | Media queries for component internals | @container @lg:grid-cols-2 | @media (min-width: ...) inside component | Medium | https://github.com/tailwindlabs/tailwindcss-container-queries |
| 50 | 49 | Interactivity | Group and Peer | Style based on parent/sibling state | group-hover peer-checked | JS for simple state interactions | group-hover:text-blue-500 | onMouseEnter={() => setHover(true)} | Low | https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state |
| 51 | 50 | Customization | Arbitrary Values | Use [] for one-off values | w-[350px] for specific needs | Creating config for single use | top-[117px] (if strictly needed) | style={{ top: '117px' }} | Low | https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values |
| 52 | 51 | Colors | Theme color variables | Define colors in Tailwind theme and use directly | bg-primary text-success border-cta | bg-[var(--color-primary)] text-[var(--color-success)] | bg-primary | bg-[var(--color-primary)] | Medium | https://tailwindcss.com/docs/customizing-colors |
| 53 | 52 | Colors | Use bg-linear-to-* for gradients | Tailwind v4 uses bg-linear-to-* syntax for gradients | bg-linear-to-r bg-linear-to-b | bg-gradient-to-* (deprecated in v4) | bg-linear-to-r from-blue-500 to-purple-500 | bg-gradient-to-r from-blue-500 to-purple-500 | Medium | https://tailwindcss.com/docs/background-image |
| 54 | 53 | Layout | Use shrink-0 shorthand | Shorter class name for flex-shrink-0 | shrink-0 shrink | flex-shrink-0 flex-shrink | shrink-0 | flex-shrink-0 | Low | https://tailwindcss.com/docs/flex-shrink |
| 55 | 54 | Layout | Use size-* for square dimensions | Single utility for equal width and height | size-4 size-8 size-12 | Separate h-* w-* for squares | size-6 | h-6 w-6 | Low | https://tailwindcss.com/docs/size |
| 56 | 55 | Images | SVG explicit dimensions | Add width/height attributes to SVGs to prevent layout shift before CSS loads | <svg class='size-6' width='24' height='24'> | SVG without explicit dimensions | <svg class='size-6' width='24' height='24'> | <svg class='size-6'> | High |