fecode-cli 1.0.0

package/skills/react/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: react
+description: React component architecture, state management, effect guidelines, and rendering behavior.
+category: framework
+version: 2.1.0
+---
+
+## When to use
+
+- writing React components
+- managing React state
+- authoring custom hooks
+- React application
+- JSX/TSX React work
+
+## When not to use
+
+- non-React frontend work
+
+## Instructions
+
+### Project Detection & Existing Rules
+- **Inspect package.json**: Identify the React version (e.g. 17 vs 18 vs 19).
+- **Inspect established conventions**: Check how the project handles state, side effects, and composition.
+- **Follow existing patterns**: Do not impose a new architecture (like switching state management libraries) simply because it is preferred, unless explicitly requested.
+
+### Core Mental Model
+- **Components**: UI rendering units receiving inputs (props) and returning UI.
+- **Props**: Immutable inputs from parents.
+- **State**: Owned mutable UI state; changing it triggers re-renders.
+- **Derived Values**: Variables calculated from props or state during render. They are not state themselves.
+- **One-way Data Flow**: Data flows down, actions flow up.
+
+### Common Failure Modes
+- **Stale Closure**: 
+  - *What it looks like*: A function (like inside an effect or timeout) uses an old value of state or props, rather than the latest.
+  - *Common cause*: Missing or incorrect dependency arrays in hooks (`useEffect`, `useCallback`).
+  - *What to inspect*: The dependency array of the hook and the variables referenced inside the closure.
+  - *Appropriate fix*: Add missing dependencies, use the functional state updater (e.g., `setCount(c => c + 1)`), or use `useRef` for values that shouldn't trigger renders but need to be fresh.
+- **Infinite Effect Loop**:
+  - *What it looks like*: The browser hangs or the console floods with re-render warnings.
+  - *Common cause*: Unstable dependencies (e.g., creating a new object/array/function on every render and passing it to a dependency array) or state updates inside effects that re-trigger the same effect.
+  - *What to inspect*: The dependency array and state setters inside the effect. 
+  - *Appropriate fix*: Stabilize dependencies with `useMemo`/`useCallback`, move logic inside the effect, or determine whether the effect should exist at all (often it can be derived during render).
+- **State Out of Sync**:
+  - *What it looks like*: Updating one piece of state doesn't update related UI.
+  - *Common cause*: Duplicated state (e.g., passing a prop and storing it in state) or derived state stored separately.
+  - *What to inspect*: Multiple competing sources of truth.
+  - *Appropriate fix*: Lift state up or compute the derived value directly during render.
+- **Incorrect Keys**:
+  - *What it looks like*: List items re-render completely, input focus is lost, or the wrong item is deleted.
+  - *Common cause*: Using array indexes as keys when list ordering or identity changes (e.g., filtering, sorting, or prepending items).
+  - *What to inspect*: The `key` prop on mapped list elements.
+  - *Appropriate fix*: Use a unique, stable identifier (like a database ID) for the `key`. Array indexes are only acceptable if the list is completely static and never changes order or size.
+- **Hydration / Server Rendering Problems**:
+  - *What it looks like*: Console warnings about text content not matching between server and client, or broken styling on load. (Only relevant when the project uses SSR/server rendering like Next.js or Remix).
+  - *Common cause*: Using browser-only values (like `window.innerWidth` or `localStorage`) during the initial render.
+  - *Appropriate fix*: Wait until the component mounts (inside `useEffect`) to read browser-only values, or conditionally render the client-specific UI.
+
+## Rules
+
+### State
+Before adding state, determine:
+- Is the value independently mutable?
+- Can it be derived from existing props/state?
+- Who owns the value?
+- Does another component need it?
+Prefer derived values when possible. Avoid duplicated sources of truth. 
+*Why*: Deriving values guarantees they are always in sync with the source of truth, eliminating entire classes of synchronization bugs.
+
+### Effects
+Before adding `useEffect`, determine:
+- Is React synchronizing with an external system?
+- Could this logic happen during render?
+- Could this logic happen inside an event handler?
+- Is this actually derived state?
+Prefer avoiding an effect when no external synchronization is required.
+*Good*: subscriptions, timers, DOM synchronization, external APIs where appropriate.
+*Bad*: deriving one state value from another, transforming props into state unnecessarily, responding to a button click that belongs in an event handler.
+
+### Component Extraction
+Before extracting a component, determine:
+- Does it have a clear responsibility?
+- Does extraction improve readability?
+- Is the component actually reusable?
+- Does extraction clarify state ownership?
+Do not extract every small JSX fragment. Only extract when it serves a structural, reuse, or performance purpose.
+
+### Custom Hooks
+Before creating a custom hook, determine whether:
+- stateful behavior is reused
+- effect/subscription logic is reused
+- a meaningful behavioral abstraction exists
+Do not create hooks merely to move code into another file.
+
+### Context
+Before introducing Context, determine:
+- Is the value genuinely shared across a subtree?
+- Would composition (passing components as props/children) solve the problem?
+- Is the value application-wide or merely needed by nearby components?
+Do not use Context as a default replacement for props.
+Do not introduce a state-management library unless requested or already used.
+
+### Memoization
+Before using `useMemo`, `useCallback`, or `React.memo`, determine whether there is an actual performance problem.
+Prefer simple code unless profiling or a clear rendering-cost problem justifies memoization. Memoization has its own complexity, costs memory, and is not automatically an optimization.
+
+### Controlled vs Uncontrolled Inputs
+Controlled when:
+- UI state must immediately drive application state
+- validation depends on current value
+- other UI reacts to the value
+Uncontrolled when:
+- the form is simple
+- DOM ownership is sufficient
+- continuous React state updates are unnecessary
+Do not prescribe one universally.
+
+### Server State vs UI State
+Make the distinction clear:
+- *UI state*: modal open/closed, selected tab, input value.
+- *Server state*: API data, remote resources, cacheable backend data.
+Do not treat server data as ordinary local component state when the project already has an established server-state/data-fetching solution (like React Query, SWR, Apollo, or framework-specific routers). Do not introduce a new library.
+
+## Workflow
+
+1. **Inspect package.json and React version**: Understand what APIs are available.
+2. **Inspect nearby components**: Understand the context of the files you are modifying.
+3. **Identify existing state/data-fetching conventions**: Respect the established architecture.
+4. **Identify ownership of the state being changed**: Ensure you modify the state at the correct level of the component tree.
+5. **Determine whether the change needs state, derived values, effects, context, or a custom hook**: Apply the decision rules before writing code.
+6. **Make the smallest change consistent with existing architecture**: Do not blindly rewrite surrounding code or impose new patterns.
+7. **Check loading, error, empty, and interaction states**: Ensure the UI handles edge cases gracefully where relevant.
+8. **Run the project's appropriate verification commands**: Verify the changes using the project's actual lint, typecheck, and test scripts.
+
+## Anti-Patterns
+
+- **Unnecessary useEffect**
+  - *What*: Using an effect to update a state variable based on a change in another state variable or prop.
+  - *Why*: It causes unnecessary extra renders (cascading renders) and makes data flow harder to trace.
+  - *Instead*: Compute the value directly during render.
+- **Duplicated derived state**
+  - *What*: Copying a prop into local state to format it or modify it slightly.
+  - *Why*: The local state becomes disconnected from the prop. If the parent updates the prop, the local state won't automatically update without complicated effect synchronization.
+  - *Instead*: Derive the formatted value during render.
+- **Premature memoization**
+  - *What*: Wrapping every function in `useCallback` and every variable in `useMemo` by default.
+  - *Why*: It harms code readability, increases memory overhead, and often provides zero performance benefit unless passed to a heavily re-rendered or explicitly memoized child component.
+  - *Instead*: Write simple code first. Optimize only when a performance issue is observed.
+- **Giant components**
+  - *What*: Placing hundreds of lines of JSX and complex state logic into a single monolithic component.
+  - *Why*: It creates a maintenance nightmare, mixes concerns, and causes the entire tree to re-render for minor local state changes.
+  - *Instead*: Extract focused child components with clear responsibilities.
+- **Unnecessary context**
+  - *What*: Putting a value into a React Context provider just to avoid passing it down one or two levels.
+  - *Why*: Context couples components to the provider, making them harder to reuse, and causes all consumers to re-render when the context value changes.
+  - *Instead*: Use prop drilling for shallow trees, or component composition (passing JSX as `children`).
+- **Unnecessary abstraction**
+  - *What*: Creating highly generic, prop-heavy "smart" components (like a `BaseButton` that takes 30 props) instead of keeping things simple.
+  - *Why*: The abstraction becomes too rigid and hard to understand.
+  - *Instead*: Prefer simple, composable components over complex configurations.
+- **Direct mutation**
+  - *What*: Writing `state.user.name = "Alice"` instead of using a setter function.
+  - *Why*: React relies on object identity (reference equality) to trigger re-renders. Direct mutation silently changes the object but skips the render.
+  - *Instead*: Always create new objects/arrays when updating state (`setUser({ ...user, name: "Alice" })`).
+- **Changing architecture without inspecting the project**
+  - *What*: Installing a state management library like Zustand or Redux into a project that successfully uses React Context.
+  - *Why*: It fragments the codebase and creates inconsistencies.
+  - *Instead*: Adapt to the existing patterns unless explicitly requested to migrate.
+
+## Examples
+
+### Derived Value
+
+Bad:
+```tsx
+const [fullName, setFullName] = useState("");
+
+useEffect(() => {
+  setFullName(`${firstName} ${lastName}`);
+}, [firstName, lastName]);
+```
+
+Better:
+```tsx
+const fullName = `${firstName} ${lastName}`;
+```
+
+### Event Handler vs Effect
+
+Bad:
+```tsx
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+useEffect(() => {
+  if (isSubmitting) {
+    postData().then(() => setIsSubmitting(false));
+  }
+}, [isSubmitting]);
+
+const handleClick = () => setIsSubmitting(true);
+```
+
+Better:
+```tsx
+const [isSubmitting, setIsSubmitting] = useState(false);
+
+const handleClick = async () => {
+  setIsSubmitting(true);
+  await postData();
+  setIsSubmitting(false);
+};
+```

package/skills/responsive-design/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: responsive-design
+description: Responsive layout design and debugging for interfaces that must work correctly across viewport sizes. Apply when creating new responsive layouts, fixing broken behavior at specific widths, adapting existing desktop UI for mobile, implementing fluid typography and spacing, debugging horizontal overflow, or reasoning about how UI components should behave between breakpoints.
+category: frontend
+version: 1.0.0
+---
+
+# Responsive Design
+
+## When to use
+- Creating new layouts that must work at multiple viewport widths
+- Fixing broken or degraded behavior at specific screen sizes
+- Adapting existing desktop-first UI for mobile viewports
+- Implementing fluid typography, spacing, or container sizing
+- Debugging unexpected horizontal scrolling or overflow
+- Reasoning about navigation behavior at small sizes
+
+## When not to use
+- Component-level logic with no layout impact
+- Backend or data-layer work
+- Accessibility-only improvements unrelated to layout
+
+## Instructions
+- Reason about content constraints and available space before reaching for media query solutions.
+- Breakpoints should emerge from where content breaks, not from device specification lists.
+- Design for behavior between breakpoints — not just at standard sm/md/lg values.
+- Horizontal overflow is a defect unless explicitly required; treat it that way.
+- Fluid sizing through relative units, clamp(), and intrinsic layout should reduce the need for many breakpoints.
+- Inspect the project's existing responsive conventions before introducing new patterns.
+
+## Design Thinking for Responsive Interfaces
+
+Before implementing any responsive behavior, reason through:
+
+1. **What does the content require?** Some content is inherently wide (data tables); some can reflow naturally (cards, text). Understand the content first.
+2. **What is the most constrained valid layout?** Start from the narrowest layout that works, then consider how it should expand.
+3. **Where does the layout actually break?** Find the real breakpoint by considering content, not by targeting device widths.
+4. **What changes between viewport sizes?** Layout, typography, spacing, navigation, interaction — identify all axes of change.
+5. **How should components behave?** Sidebars, tables, cards, modals, and navbars each have distinct responsive behaviors.
+6. **What existing conventions does the project use?** Breakpoint values, container widths, column behavior — inspect before overriding.
+
+## Breakpoints
+
+**Use breakpoints where content requires them, not at arbitrary device widths.**
+
+Signs a breakpoint is needed:
+- Content becomes unreadable or inaccessible at a particular width
+- A layout composition stops working (columns become too narrow, overflow occurs)
+- Navigation must fundamentally change
+
+Signs a breakpoint is unnecessary:
+- You are adding it "for mobile" without a specific layout failure
+- The layout was already fluid and would have worked without it
+- You are targeting a device resolution rather than a content constraint
+
+**Avoid breakpoint proliferation.** Three to four thoughtful breakpoints serve most layouts better than seven device-specific ones.
+
+**Always check behavior between breakpoints.** Resize the viewport gradually, not just by snapping between predefined sizes.
+
+## Fluid Layouts
+
+**Container strategy**
+- Max-width containers centered with `margin: auto` handle wide-screen scaling without additional breakpoints
+- `min-width: 0` prevents flex/grid children from overflowing their containers
+
+**Flexible columns**
+- CSS Grid with `auto-fill` / `auto-fit` and `minmax()` handles column reflow without any media queries: `grid-template-columns: repeat(auto-fill, minmax(min(100%, 280px), 1fr))`
+- Flexbox with `flex-wrap: wrap` and `flex-basis` allows natural reflow
+
+**Relative and intrinsic sizing**
+- Prefer `%`, `fr`, `ch`, `em`, `rem` over `px` for dimensions that should scale
+- `min-width`, `max-width`, and `min-content` / `max-content` are layout tools, not edge cases
+- `clamp(min, preferred, max)` handles fluid scaling without breakpoints for font sizes and spacing
+
+## Typography in Responsive Layouts
+
+**Heading size**
+- Display headings that are appropriate at 1400px are often overwhelming on 375px
+- Use `clamp()` for fluid heading sizes: `font-size: clamp(1.5rem, 4vw, 3rem)`
+- Alternatively, reduce heading scale at narrower breakpoints
+
+**Body text**
+- Body text should remain readable at all widths — avoid sizes below 14px on mobile
+- Line length (measure) should stay between 55–80ch; full-width body text on wide screens needs a `max-width` constraint
+
+**Long content behavior**
+- Define how long text behaves: truncation with ellipsis, clamped lines (`-webkit-line-clamp`), or full wrapping
+- Labels, button text, and navigation items may need different truncation strategies
+- Test with realistic content, not short placeholder text
+
+## Navigation
+
+Navigation often requires the most significant behavior change between viewport sizes.
+
+**Desktop navigation**
+- Horizontal nav bars work until they overflow; plan the overflow behavior before it becomes a bug
+- Ensure keyboard and focus order remain logical
+
+**Mobile navigation**
+- Collapsed navigation (hamburger/drawer/bottom bar) each have different interaction models — choose deliberately based on depth and frequency of navigation
+- Touch targets must be at least 44×44px
+- Drawer/modal navigation must be keyboard-accessible and focusable
+
+**Collapsing controls**
+- Secondary toolbars, filter bars, and action sets often need to collapse or scroll on small screens
+- Define the priority of visible actions when space is constrained
+
+## Component Behavior Across Widths
+
+Different components require different responsive strategies:
+
+| Component | Common responsive behavior |
+|-----------|---------------------------|
+| **Tables** | Horizontal scroll, card reflow, or column collapsing |
+| **Cards** | Reflow from multi-column to single-column grid |
+| **Forms** | Stack labels above inputs; adjust field widths |
+| **Sidebars** | Collapse into drawer, accordion, or hidden panel |
+| **Dialogs/Modals** | Full-screen on mobile; centered overlay on desktop |
+| **Toolbars** | Collapse secondary actions into overflow menu |
+
+Do not apply the same responsive strategy to every component type. Match the strategy to the component's use case.
+
+## Overflow
+
+**Horizontal overflow is always a defect unless explicitly required.**
+
+Common causes:
+- Fixed-width children inside fluid parents
+- Long unbreakable strings (URLs, code, long words without `overflow-wrap`)
+- Tables without an overflow strategy
+- Images without `max-width: 100%`
+- Absolute/fixed positioned elements
+
+Debugging overflow:
+1. Add `outline: 1px solid red` to suspect elements temporarily
+2. Check `min-width` constraints on flex/grid children (`min-width: 0` is frequently needed)
+3. Inspect for any element with a hard-coded `width` wider than the viewport
+
+## Design Workflow
+
+1. Understand the content requirements and interaction model.
+2. Inspect the project's existing responsive conventions (breakpoint values, container widths, grid patterns).
+3. Identify the most constrained layout that must work.
+4. Establish fluid base structure using relative units and intrinsic sizing.
+5. Define breakpoints only where the layout genuinely breaks.
+6. Implement responsive typography using `clamp()` or breakpoint-specific scale.
+7. Handle navigation and component state changes at key widths.
+8. Check for and eliminate horizontal overflow.
+9. Review intermediate viewport widths — not just the breakpoint snap-points.
+10. Verify with realistic content lengths, not just short placeholder text.
+
+## Self-Review Checklist
+
+Before considering responsive work complete:
+
+- Does the layout work at 320px, 375px, 768px, 1024px, 1280px, and 1440px?
+- Does anything break between those widths?
+- Is there any horizontal overflow?
+- Does the typography remain readable at all widths?
+- Are touch targets at least 44×44px on mobile?
+- Does navigation function at mobile sizes?
+- Are all interactive states accessible at all widths (not just hover, which doesn't exist on touch)?
+- Does the layout use the project's existing breakpoint conventions?
+
+## Avoid
+
+- Desktop layout simply shrinking linearly — content often requires structural changes, not just width reduction.
+- Excessive breakpoints for every device size — let content drive breakpoints.
+- Fixed pixel widths on components that must live in fluid parents.
+- Horizontal overflow without an intentional overflow strategy.
+- Touch targets smaller than 44×44px.
+- `hover`-only interaction states — touch devices do not have hover.
+- Duplicated desktop and mobile markup without a clear reason.
+- Breakpoint-specific hacks that fix one width while breaking another.
+
+## Examples
+
+### Example: Card grid reflow without breakpoints
+Use intrinsic responsive layout that reflows naturally:
+```css
+.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, 280px), 1fr));
+  gap: var(--space-4);
+}
+```
+This single rule handles all viewport widths without any media queries.
+
+### Example: Reasoning about a sidebar
+Rather than hiding the sidebar at mobile widths with `display: none`, consider: What does the sidebar contain? If it contains navigation, it must be accessible somehow at mobile — as a drawer, a bottom nav, or an inline collapsed section. "Hide it" is not a responsive strategy.

package/skills/svelte/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: svelte
+description: Svelte components, compiler-driven reactivity, local/derived state, and SvelteKit boundaries.
+category: framework
+version: 2.1.0
+---
+
+## When to use
+
+- authoring Svelte components
+- handling Svelte reactive statements
+- working with Svelte stores or SvelteKit
+
+## Instructions
+
+### Project Detection & Existing Rules
+- **Version Detection**: The agent must inspect the project's Svelte version (e.g., Svelte 3/4 vs Svelte 5).
+- Distinguish modern Svelte patterns (like runes in Svelte 5: `$state`, `$derived`) from older syntax.
+- **Do not blindly apply legacy syntax** to a modern project, and do not force modern runes on older projects.
+- **SvelteKit Check**: Inspect if the project uses SvelteKit. **Do not assume SvelteKit** when the project is plain Svelte.
+
+### Core Mental Model
+- **Component-based UI**: Svelte compiles components to highly efficient imperative code.
+- **Compiler-driven reactivity**: Assignments (or runes) trigger updates, no virtual DOM overhead.
+- **Local State**: State scoped to a component.
+- **Derived State**: Values that automatically update when dependencies change.
+- **Effects**: Side-effects triggered by state changes.
+
+### Components
+- Single-file components (`.svelte`) contain `<script>`, HTML markup, and scoped `<style>`.
+- Understand composition, slots/snippets, and clear component boundaries.
+
+### Props
+- Explain the appropriate prop mechanism for the project's Svelte version (`export let` in Svelte 3/4 vs `let { prop } = $props()` in Svelte 5).
+- Respect existing project conventions.
+
+### Reactivity
+- Cover local state, derived values, effects, and dependency tracking.
+- Explain version-specific differences when relevant (`$:` vs runes).
+
+### Events / Communication
+- Parent-child communication via props and events.
+- Use callbacks or event dispatchers (`createEventDispatcher`) appropriate to the project's Svelte version.
+- Do not force legacy APIs when modern conventions are already used.
+
+### Stores
+- Stores are useful for shared state, cross-component state, or application-level state.
+- **Do not use stores for state that naturally belongs to a component.** Keep local state local.
+
+### Lifecycle
+- Initialization, cleanup, subscriptions, and browser-only behavior (`onMount`, `onDestroy`).
+
+### SvelteKit
+- **Only apply SvelteKit guidance when the project actually uses SvelteKit.**
+- Routing, load/data patterns (`+page.ts`, `+page.server.ts`).
+- Form actions and server/client boundaries.
+- Hooks and page/layout structure.
+
+### Common Failure Modes
+- **Incorrect reactive assumptions**: Expecting reactivity from object mutation without reassignment (Svelte 3/4).
+- **Unnecessary stores**: Using a global store for a value that is only used inside one component.
+- **Browser/server mistakes**: Using `window` during SSR.
+- **Lifecycle misuse**: Running heavy logic in component initialization instead of `onMount`.
+- **Unnecessary client-side work**: Failing to utilize SvelteKit server load functions.
+
+## Anti-Patterns
+
+- **Mutating objects without reassignment (Svelte 3/4)**
+  - *What*: Calling `.push()` on an array instead of reassigning it.
+  - *Why*: The Svelte compiler tracks assignments (`=`). Array `.push()` or object mutations won't trigger updates.
+  - *Instead*: Reassign the variable (e.g. `arr = [...arr, newItem]`).
+- **Overusing global stores**
+  - *What*: Creating a store for simple component-level UI state (like an "isOpen" toggle).
+  - *Why*: It breaks encapsulation and makes components harder to test.
+  - *Instead*: Pass props or use context for localized tree state.
+
+## Workflow
+
+### Debugging
+- Inspect reactive statements and dependencies.
+- Use `console.log` inside reactive blocks to trace data flow.
+- Follow `frontend-debugging` workflow when diagnosing rendering problems.
+
+### Verification
+- Typecheck using `svelte-check` or the project's `tsc` setup.
+- Run project lint, test, and build scripts.

package/skills/tailwind/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: tailwind
+description: Tailwind CSS utility composition, responsive behavior, design tokens, and state variants.
+category: styling
+version: 2.1.0
+---
+
+## When to use
+
+- styling components with Tailwind CSS
+- building responsive layouts with utility classes
+
+## Instructions
+
+### Project Detection & Existing Rules
+- **Inspect package.json & Configuration**: Check Tailwind version, `tailwind.config.js`, CSS entrypoints, and existing utility conventions.
+- **Design Tokens**: Identify existing design tokens (custom colors, spacing, typography, radius, shadows). **Prefer existing project tokens.**
+- **Do not force Tailwind** onto projects that do not use Tailwind.
+
+### Design Tokens
+- Do not introduce arbitrary values (`[#ff0000]`) when existing project tokens or standard scales can be used.
+
+### Composition
+- Group utilities logically (e.g., layout first, then spacing, typography, visual).
+- Build reusable component patterns cleanly.
+- Keep class strings understandable.
+- Avoid duplicated utility combinations by extracting heavily repeated patterns into component abstractions (use React/Vue/Svelte components, avoid `@apply` unless it is a strong project convention).
+
+### Responsive
+- Use responsive variants (`sm:`, `md:`, `lg:`) for fluid viewport adaptations.
+- Understand mobile-first behavior (unprefixed is mobile).
+- **Do not simply add every breakpoint.** Design for fluidity.
+- Follow `responsive-design` guidance for viewport behavior.
+
+### State
+- Use interactive state modifiers (`hover:`, `focus:`, `focus-visible:`, `active:`, `disabled:`).
+- Use `group` and `peer` for complex relational state styling.
+
+### Dark Mode
+- Respect the project's existing dark-mode strategy (e.g., `class` strategy vs `media`).
+- Do not introduce a new strategy. Use `dark:` variants appropriately.
+
+### Arbitrary Values
+- Arbitrary values are justified for highly specific, one-off cases (e.g., a specific background image position or precise translation).
+- Prefer project tokens or standard scales when appropriate.
+- Do NOT make arbitrary values categorically forbidden, but use them sparingly.
+
+### Component Boundaries
+- Do not create component abstractions solely because a class list is long.
+- Balance readability, reuse, and project conventions.
+
+### Common Failure Modes
+- **Contradictory utilities**: Applying both `p-4` and `p-6` to the same element, causing specificity surprises.
+- **Excessive arbitrary values**: Flooding the codebase with `[14px]` instead of using `text-sm`.
+- **Duplicated classes**: Repeating the exact same long string of classes across multiple sibling elements instead of mapping over data or extracting a component.
+- **Breakpoint proliferation**: Hardcoding too many breakpoint overrides instead of trusting flexible layouts like Flexbox or Grid.
+- **Ignoring existing tokens**: Hardcoding hex codes instead of using the theme configuration.
+- **Inconsistent responsive behavior**: Forgetting to scale typography along with layout at different viewports.
+
+## Anti-Patterns
+
+- **Arbitrary Values over Scale Tokens**
+  - *What*: Writing `w-[64px]` instead of `w-16`.
+  - *Why*: It breaks design consistency and bloats the generated CSS.
+  - *Instead*: Use the standard tailwind scale.
+- **Heavy use of @apply**
+  - *What*: Putting `@apply text-sm font-bold text-red-500` inside CSS files frequently.
+  - *Why*: It defeats the purpose of utility-first CSS and creates hidden specificity issues.
+  - *Instead*: Extract the HTML into a reusable framework component (React/Vue/Svelte).
+
+## Workflow
+
+### Verification
+- Use project linting, build, typecheck, and test scripts to verify the styling does not break UI components.