# Think Company — AI Agent Coding Instructions These instructions apply to all AI-assisted coding at Think Company. They encode our front-end development standards and are the authoritative source for the per-tool files (`CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md`). --- ## Core Principles - Write code that is readable, modular, and accessible by default. - Prefer explicit over clever. Prioritize the next developer's ability to understand and change the code. - Follow the conventions already in use in the project. When in doubt, match the surrounding code. - Do not add features, abstractions, or error handling beyond what the task requires. - Validate at system boundaries (user input, external APIs). Trust internal code. --- ## TypeScript - All new code must be TypeScript. Do not introduce plain `.js` files. - Enable `strict: true` in `tsconfig.json`. Never disable strict mode to work around a type error — fix the type. - Never use `any`. Prefer `unknown` when the type is genuinely unknown and narrow it explicitly. - Prefer `interface` for object shapes that may be extended; use `type` for unions, intersections, and aliases. - Use built-in utility types (`Partial`, `Required`, `Pick`, `Omit`, `Readonly`, `ReturnType`, etc.) rather than re-implementing them. - Keep type definitions co-located with the code that uses them. Only promote to a shared `types/` directory when truly shared. - Avoid type assertions (`as Foo`) except at verified system boundaries. Never use non-null assertions (`!`) without a comment explaining why the value cannot be null. - Prefer `satisfies` over `as` when you need to validate a value against a type without widening it. - Use `as const` to lock object and tuple literals to their narrowest types (e.g. to derive a union from an array of values). - Model mutually-exclusive states as discriminated unions (a shared literal `kind`/`status` tag), not a bag of optional fields. Narrow them with `switch`. - For data crossing a system boundary (API responses, form input, `localStorage`), type it as `unknown` and validate at runtime with a schema validator (Zod or Valibot) before use. Do not trust a hand-written `as` cast on external data. - Enable `noUncheckedIndexedAccess` so indexed access (`arr[i]`, `record[key]`) is typed as possibly `undefined`. Consider `exactOptionalPropertyTypes` per project — it is stricter and can fight library interop. --- ## JavaScript - Use `const` by default. Use `let` only when the value will be reassigned. Never use `var`. - Declare variables close to where they are first used, not in a block at the top of the scope. - Use `===` and `!==`. Never `==` or `!=`. - Be explicit in conditions when the type is ambiguous. Truthy shortcuts hide bugs around `0`, `''`, and `null` — prefer `if (count > 0)` over `if (count)` and `if (name != null)` over `if (name)`. - Use template literals for string interpolation. No string concatenation. - Arrow functions for callbacks and closures. Named function declarations for top-level functions (better stack traces). - Use ES modules (`import`/`export`). Prefer named exports over default exports for non-component modules. - Use the modern operators: optional chaining (`?.`), nullish coalescing (`??`), and logical assignment (`??=`, `||=`, `&&=`). Use `??` (not `||`) for defaults so `0` and `''` are preserved. - Use `async`/`await` over hand-rolled promise chains. Run independent async work concurrently with `Promise.all`; use `Promise.allSettled` when failures should not short-circuit. Sequential `await`s on independent calls are a performance bug. - Iterate with `for...of` and array methods. Never use `for...in`; use `Object.keys`/`Object.values`/`Object.entries` for objects. - Bind events with `addEventListener` — never inline `on*` attributes. Use `IntersectionObserver`/`ResizeObserver` instead of polling `scroll`/`resize`; debounce or throttle high-frequency handlers. - Use trailing commas in multi-line objects, arrays, and parameter lists. - When converting strings to numbers, use `Number()` or `Number.parseInt(value, 10)` with an explicit radix. - Never use `eval` or the `Function` constructor. - Avoid assignments inside conditionals. --- ## React - Use functional components exclusively. Do not write new class components. - Use hooks for all state and side effects. Do not use `componentWillMount`, `componentWillReceiveProps`, or other deprecated lifecycle methods. - One component per file. Filename and component name must match. Use PascalCase (e.g., `UserCard.tsx`). - Always use `.tsx` for files containing JSX. - Use double quotes for JSX attributes; single quotes for all other JS/TS strings. - Do not use array index as `key` prop. Use a stable, unique ID. - Do not spread props onto DOM elements without filtering (`{...rest}` onto a `
` leaks unknown attributes). - State management — match the tool to the *kind* of state: - Local component state: `useState` (or `useReducer` for complex transitions). - Shared across a small subtree: React Context. Do not reach for a global store just to avoid prop drilling. - Server state (API data, caching, revalidation): TanStack Query or SWR. Do not put server data in Redux. - URL state (filters, pagination): keep it in query params via the router. - Global client state: Zustand or Jotai for lighter needs; Redux Toolkit (RTK) on larger projects. - `useEffect` is for synchronizing with external systems, not for deriving data. Compute derived values during render — do not mirror props into state via an effect. Declare every reactive dependency (do not disable `react-hooks/exhaustive-deps`), and return a cleanup function for subscriptions, timers, and connections. - Extract reusable stateful logic into custom hooks (`use`-prefixed), not HOCs or render props. - Wrap failure-prone subtrees (data fetching, third-party widgets, route components) in an error boundary. - In React 19 / Next.js App Router, components are Server Components by default. Mark components that use state, effects, or browser APIs with `'use client'`, and push client components as far down the tree as possible. - Do not use `isMounted`. It is deprecated and unavailable in functional components. - Conditional rendering: avoid nested ternaries. Break complex conditionals into separate components. - PropTypes are not required in TypeScript projects — use TypeScript types instead. --- ## CSS - Author **vanilla CSS** on all projects. Use **Tailwind CSS** as a utility layer where the project and client permit. Sass/SCSS is no longer the default — projects already on Sass may continue, but do not start new work in it. - Use CSS custom properties for all design tokens (colors, spacing, type scale, z-index, breakpoints). Define them on `:root`. - Do not use vendor mixin libraries. Avoid manual vendor prefixes — use Autoprefixer in the build pipeline. - Architecture follows SMACSS: Settings → Base → Layout → Modules → Helpers. - State classes: prefix with `is-` or `has-`. - Subcomponents: `[module]-[subcomponent]`. - Modifiers: `[module]--[modifier]`. - Name selectors based on function, not appearance. Lowercase, hyphen-separated. - Do not use IDs as styling hooks. Use class names. - Keep specificity low. Author from general to specific. - Nest no more than 3 levels deep (including pseudo-classes and pseudo-elements). - Do not use `!important` except to override unmodifiable third-party styles (add a comment explaining why). - Use `box-sizing: border-box` globally via the inherit pattern. - Use relative units (`em`, `rem`, `%`) over `px` wherever possible. - Do not use `line-height` with a unit. Use a unitless ratio (e.g., `line-height: 1.5`). - Declaration order within a rule: custom properties → layout → box model → typography → visual → interaction → animation. - Name and place media queries alongside their base ruleset, smallest to largest (mobile-first). ### File naming convention `[category].[partial-name].css` Examples: `settings.tokens.css`, `layout.grid.css`, `module.card.css`, `helpers.spacing.css` ### Tailwind - Use Tailwind only where the team has agreed and no conflicting CSS architecture exists. - Order utility classes layout → box model → typography → visual → interaction → animation; enforce with the Prettier Tailwind plugin. - Prefer extracting a reusable component over `@apply`. Use `@apply` only where JSX components aren't available (e.g. CMS templates). - Map tokens in config to custom properties; don't use arbitrary values (`w-[347px]`) for things that should be tokens. ### Modern CSS features These have reached broad/Baseline support — treat them as first-class tools, not experimental: - **Cascade layers (`@layer`)** to manage specificity across resets, third-party styles, and your own code without `!important`. - **Container queries** when a component's layout depends on its container's size rather than the viewport. - **`:has()`** to style a parent based on its descendants — replaces many JS class-toggling patterns. - **Logical properties** (`margin-inline`, `padding-block`, `border-inline-start`) over physical ones for RTL-friendly layouts. - **Modern color** — `oklch()` for perceptually-uniform colors, `color-mix()` to derive related colors from a token. - **Custom properties** for all design tokens (colors, spacing, type scale, z-index). --- ## HTML - All HTML must conform to the HTML5 spec. Validate with the W3C validator. - Write semantic markup. Use the correct element for the meaning, not for the appearance. - Use HTML5 sectioning elements (`
`, `
`, `
`, `