project-landlord

Design System and Product UI Guidance

Purpose

This document defines the visual and interaction direction for the application. It should be used as implementation guidance when building the product with Tailwind CSS, shadcn/ui, React, and TypeScript.

This guidance should influence:

This is not just a style guide. It is a product-experience guide.

Product Design Goal

The application should feel like a calm mobile financial workspace for shared housing bills.

It should not feel like:

It should feel closer to:

Core emotional goals:

Design Principles

1. Trust through clarity

Users should always understand:

Amounts, due dates, statuses, and actions should never compete for attention.

2. Summary first, detail second

Show the answer first. Then let the user drill into supporting context.

Every core screen should surface the most important answer near the top.

3. One job per screen

Every screen should have a clear primary purpose and a clear next action.

Avoid multi-purpose screens that try to do too much at once.

4. Mobile first for real

This does not mean responsive after the fact. It means the primary workflow should be designed around a phone-sized viewport first.

5. Motion with purpose

Motion should clarify, not decorate. Animation should improve continuity, reduce abruptness, and reinforce state change.

6. Calm, not dull

The UI should be visually quiet, but still feel premium and polished. Whitespace, typography, and motion should do the heavy lifting.

7. Desktop expands mobile

Desktop should provide more breathing room and faster scanning. It should not become a dense enterprise control panel.

Technical Stack Assumptions

Brand and Visual Direction

Brand color

Use teal as the primary brand color.

Preferred Tailwind brand scale:

Why teal

Teal provides:

Visual tone

The UI should feel:

Avoid:

Color System

Neutral palette

Use zinc as the primary neutral family.

Recommended usage:

Dark mode direction:

Semantic colors

These should be distinct from the brand color.

Use:

Suggested mappings:

Use soft backgrounds for alerts and badges:

Do not use the brand teal for every semantic state.

Theme Tokens

Light mode intent

Dark mode intent

Typography

Typeface

Use Inter as the primary font family.

Why Inter:

General direction

Typography should be larger than typical SaaS applications. This product should feel easy to read at a glance on a phone.

Typography rules

Tone of text

Interface copy should be:

Spacing System

Core spacing philosophy

Use spacing to create hierarchy before using borders or extra containers.

The UI should breathe.

Suggested spacing scale

Layout rules

Radius, Borders, and Shadows

Radius

The product should feel soft and modern.

Suggested radius scale:

Recommended base design token:

Borders

Borders should be subtle. Prefer low-contrast separators.

Use borders when:

Do not:

Shadows

Use very subtle shadows. Shadows are for separation, not drama.

Prefer:

Layout Rules

Mobile

Tablet

Desktop

Content width

Do not let primary content stretch too wide on desktop. Favor readable line length and focused composition.

Interaction Model

Overall interaction goal

The product should feel polished, predictable, and fast.

Interaction priorities

Preferred interaction patterns

Avoid

Motion Guidelines

Motion philosophy

Motion should improve confidence and orientation.

It should:

It should not:

High-value motion patterns

Motion feel

Avoid:

Information Hierarchy

Order of importance on billing screens

  1. What is due or what needs attention
  2. What the amount or state means
  3. What action should happen next
  4. Supporting detail
  5. History, metadata, and audit trail

Core rule

The user should not need to decode the screen to find the answer.

Examples

On a statement screen:

On a review screen:

Status Design

Importance

Status clarity is central to trust.

Users should never wonder:

Core status set

Status rules

Suggested semantic mapping:

Screen Guidance

Home

Purpose:

Structure:

Statement Screen

Purpose:

Structure:

Review / Validation Screen

Purpose:

Structure:

Split / Roommate Screen

Purpose:

Structure:

Activity / Timeline Screen

Purpose:

Structure:

Component Guidance

For the concrete component catalog (file paths, props, variants, layout rules), see docs/project/components.md. This section covers the design principles that govern all components.

Favor these primitives

Component rules

shadcn/ui usage guidance

Use shadcn/ui as a foundation, not a final design language. Customize spacing, radius, typography, and visual rhythm so the product does not look like a default starter kit.

Established Design Patterns

These patterns have been validated in the product and should be followed for consistency. They are the concrete rules derived from the principles above.

Button hierarchy

Inputs and controls

Cards and containers

Success and error states

Amounts and money

Theme-aware assets

Spacing philosophy

Page-level utility UI

Status indicators

Modals and dialogs

List rows in containers

Page transitions and loading

Multi-step form flows

Never do this

Accessibility

Requirements

Touch targets

Primary controls should be comfortably tappable on mobile. Do not use tiny targets for important workflows.

Copy and Content Guidance

Tone

Use UI language that is:

Preferred style

Avoid:

What to Avoid

Do not build the app to look like:

Avoid:

Implementation Guardrails for Claude Code

When generating UI:

When uncertain:

Final North Star

The finished product should feel like a calm, premium, mobile financial product for shared housing bills, with the interaction polish of a modern productivity tool and the trustworthiness of a consumer money app.