| name | kasuwar-gizo-design-philosophy |
| description | Stack-agnostic premium UI/UX and engineering philosophy — Apple-inspired simplicity, glassmorphism, borderless cards, domain-driven architecture, and a full set of UI/UX decision rules for tables, forms, dropdowns, empty states, and more. Apply this whenever building, styling, or reviewing frontend UI in React, Next.js, Vue, Laravel, or any other stack — including when the user asks to build or restructure a component, page, dashboard, form, or design system; mentions "premium," "glassmorphism," "Apple-inspired," or "clean UI"; asks for cards, tables, dropdowns, empty states, dark mode, or micro-interactions; or is setting conventions for a new codebase. Also consult this when reviewing existing UI code for design consistency, accessibility, or file/folder organization, even if the user doesn't explicitly ask for a "design system." |
Kasuwar Gizo — Design Philosophy & Engineering Principles
This is a reusable design and engineering philosophy — not tied to any single codebase or framework. Apply it whenever writing new UI, refactoring existing UI, or making architectural decisions about how a frontend codebase should be organized. It works the same whether the stack is Laravel + React, Node.js + Vue, Next.js, or something else entirely.
Treat this as the lens for how to build, not a spec for what to build — layer it on top of whatever feature or page the user is actually asking for.
Core Design Principles
Apple-inspired premium experience. The goal is software that feels effortless rather than merely functional. That means: simplicity in every UI element, attention to detail in micro-interactions and transitions, clean system-like typography (SF Pro, Inter, Google Sans Flex), and generous, consistent spacing on an 8px or 4px rhythm. Use blur and transparency (glassmorphism) for surfaces that should feel modern and premium — but reach for it deliberately, not on every panel.
Utility-first CSS. Prefer utility classes over custom CSS and inline styles (style={{}}); route all styling through a consistent spacing, color, and shadow scale. Never use emojis as icons — they render inconsistently across platforms and fonts. Use a real icon library instead.
No unnecessary decoration. Cards default to no borders and no shadows — let the content breathe instead of boxing it in. Only add a border when structural separation is actually needed, and even then prefer a subtle divider (border-border/20) over a thick one. If you find yourself adding a border or shadow "just in case," that's a signal to reconsider rather than a default to reach for.
Component Architecture Philosophy
Composition over complexity. Build small, focused, reusable components where each one does exactly one thing well. Configure behavior through props rather than growing a component to handle every case internally.
Single Responsibility Principle. UI components render and style; business logic lives in services, hooks, or utilities; data fetching stays out of presentational components. When a component starts doing more than one of these, that's the point to split it.
Clear separation of concerns. Server logic belongs in services or API layers, client interactivity in dedicated components or hooks, and data/types in their own domain files.
Consistency over cleverness. Use the same pattern everywhere a pattern applies — one way to fetch data, one way to structure a form, one way to compose a layout. A clever one-off is a maintenance cost later, even when it's a few lines shorter today.
Build for extensibility. Write code that's easy to change and hard to break. Avoid premature optimization, but don't paint the code into a corner either — props and hooks are the flexible seams to design in from the start.
UI/UX Design Rules
Mobile-first
Always start with the mobile layout and scale up, not the reverse. Check 375px (small phone), 768px (tablet), and 1024px+ (desktop). Touch targets need at least 44×44px, and body text needs at least 16px to stay readable on a phone.
Responsive grids
Use flexible grids (grid with minmax, or flex-wrap) instead of fixed widths. On mobile, show the core information first and fold secondary content — don't just shrink the desktop layout. Breakpoints: sm: 640px, md: 768px, lg: 1024px, xl: 1280px.
Typography
One type scale across the whole product: 12, 14, 16, 18, 24, 32, 48, 72 (or similar). Headers use a display font, bold (600–700), tight tracking. Body uses a regular-weight (400) sans-serif with 1.5 line-height. Subtle/secondary text uses a muted color and smaller size rather than a different font.
Iconography
Always pull from an icon library (Heroicons, Lucide, Feather) — never emojis, since they're font-dependent and inconsistent across platforms. Keep stroke width, size, and style consistent across every icon in the product, and pair icons with text labels where the meaning isn't self-evident.
Micro-interactions & feedback
Every interaction needs feedback: hover, focus, loading, error. Transitions should feel smooth rather than instant — 150–300ms for micro-interactions, 500ms for page transitions. Always respect prefers-reduced-motion so animation is an enhancement, not a requirement.
Dark mode
Design light and dark themes together from the start, using semantic color tokens rather than hardcoded hex values, so a component doesn't need special-casing to work in both. Check contrast in both themes — minimum 4.5:1 for text.
Code Organization Philosophy
Domain-driven structure. Organize by business domain, not technical layer — a Businesses folder holds everything related to businesses: components, hooks, services, types, and API calls together, rather than scattering them across components/, hooks/, services/ at the top level. Related code should live near related code.
UI vs. logic. Presentational components stay simple — receive props, render UI. Container components handle logic, state, and data fetching. Services and utilities own business rules, API calls, and data transformations.
Reusable shared components. UI primitives (Button, Input, Card) should be generic and reusable across the whole app; domain components should be specific to their feature. A shared/ folder holds cross-cutting utilities and components that don't belong to any one domain.
Client vs. server. In a split frontend/backend setup (React + Laravel or similar), keep the boundary clean: frontend handles UI, interactivity, client-side state, and API calls; backend handles business logic, the database, auth, and API responses. Don't mix the two in the same file.
Type safety. Use TypeScript (or the stack's equivalent) on both frontend and backend, define types for every data model, and validate at runtime with Zod or similar. Avoid any — it defeats the point of having types at all.
UI/UX Decision Rules
Use these as defaults for common UI patterns. They're meant to keep decisions consistent across a whole product rather than re-litigated component by component.
Cards — no borders, no shadows; white background in light mode, surface background in dark; padding p-4 to p-6 depending on content density.
Tables — reveal row actions on hover rather than showing them all the time; paginate at 10–25 items per page; use shimmer skeleton loaders while data loads, and a staggered fade-in for rows on first render.
Forms — labels stay visible, never placeholder-only; validate in real time on blur, with errors shown near the field; disable the submit button and show a spinner while loading; confirm success with a toast or inline message.
Dropdowns & menus — always close on click-away; use a smooth open/close transition; make the active/selected item visually obvious.
Notifications — green for success, red for error, orange/yellow for warning, blue/neutral for info; auto-dismiss non-critical toasts after 3–5 seconds.
Empty states — never a blank page. Show a helpful message, a clear call to action ("Add first business"), and an icon or illustration so it reads as an invitation rather than a dead end.
Danger zone — destructive actions get visual separation (red, positioned lower on the page), always require an explicit confirmation modal, and use unambiguous labels ("Delete" vs. "Edit") so intent is never in question.
Engineering Best Practices
Code quality
Naming: PascalCase for components, useCamelCase for hooks, camelCase for utilities, UPPER_CASE for constants. Keep files under 200–300 lines — a file that's grown past that is usually a sign it's doing more than one job. Comment only when the code genuinely needs it; well-named functions and variables should carry most of the explanation themselves. Run a linter and formatter (ESLint, Prettier) rather than relying on manual consistency.
Data fetching
Centralize API calls in a services/API layer rather than scattering fetch calls through components. Use error boundaries for graceful failure, show loading states (skeletons or spinners) instead of a blank screen, and cache where it makes sense (React Query, SWR, or similar).
Performance
Lazy-load images (loading="lazy"), virtualize long lists (react-window or similar) once a list passes ~50 items, and use memoization (React.memo, useMemo, useCallback) where re-renders are actually a measured problem — not reflexively everywhere.
Accessibility
Alt text on every meaningful image, aria-labels on icon-only buttons, full keyboard navigation for every interaction, semantic HTML (button, a, input) instead of div-based pseudo-elements, and visible focus states — never disable a focus ring without providing a replacement.
Security
Sanitize user input on both frontend and backend, serve everything over HTTPS in production, keep secrets in environment variables (never in the codebase), rate-limit API requests where the backend supports it, and use CSRF protection on forms.
Testing
Unit test business logic (utilities, services), integration test API endpoints, and cover the critical user journeys end to end (login, registration, checkout) rather than chasing 100% coverage on everything equally.
Developer Experience
Build tools and structure that make the next person working in this codebase — including a future instance of Claude — move quickly: document architecture decisions as you go, write meaningful error messages, create reusable utilities instead of duplicating logic, and let linting/formatting run automatically rather than depending on discipline. Git hooks (pre-commit, pre-push) are a good place to enforce this without needing to remember it.
Summary of Non-Negotiable Rules
These are the rules to hold the line on even under time pressure — everything else in this document is a strong default, but these are the ones worth pushing back on if a request would violate them.
| Rule | Category |
|---|
| No emojis as icons — use an icon library | Design |
| Cards have no borders or shadows by default | Design |
| Every interaction needs feedback (hover, focus, loading, error) | UX |
| Dropdowns close on click-away | UX |
| Skeleton loaders for async content | UX |
| Staggered animations for list rendering | UX |
| Mobile-first development | Engineering |
Type safety (TypeScript, Zod) — never any | Engineering |
| Clear separation of UI and business logic | Architecture |
| Consistent naming and domain-driven structure | Engineering |
| Accessibility by default (keyboard nav, focus states, semantic HTML) | Engineering |
