Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: improve CLAUDE.md contributing guide and add serena memories #2925

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve CLAUDE.md contributing guide and add serena memories #2925

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@ server/ui/assets
/audits
go.work
go.work.sum
.claude
.claude/settings.local.json
133 changes: 133 additions & 0 deletions .serena/memories/code_style_conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Code Style and Conventions

## Svelte 5 Patterns

### Props Definition

```typescript
interface Props {
class?: string;
adapter: Adapter;
}
let { class: className = '', adapter }: Props = $props();
```

### State Management

```typescript
// State
let count = $state(0);

// Computed values
const doubled = $derived(count * 2);

// Complex computed with function
const complex = $derived.by(() => {
// computation logic
return result;
});

// Effects (use sparingly - team prefers avoiding them)
$effect.pre(() => {
// side effect logic
});
```

### SuperForms Pattern

```typescript
const { form, errors, enhance } = $derived(
superForm(data, {
SPA: true,
validators: zodClient(schema),
onUpdate: async ({ form }) => {
// handle submit
},
}),
);
```

## Import Order (STRICT)

1. Node.js built-ins
2. External libraries (`svelte/**` first)
3. SvelteKit imports (`$app/**`, `$types`)
4. Internal imports (`$lib/**`)
5. Component imports (`$components/**/*.svelte`)
6. Relative imports (`./`, `../`)

## Naming Conventions

- **Files**: kebab-case (`workflow-status.svelte`)
- **Components**: PascalCase in imports, kebab-case files
- **Functions**: camelCase
- **Types/Interfaces**: PascalCase
- **Constants**: UPPER_SNAKE_CASE or PascalCase
- **CSS classes**: kebab-case with Tailwind utilities

## TypeScript Requirements

- Always use proper types (no `any`, `unknown`, or `as` assertions)
- Use `import type` for type-only imports
- Prefer interfaces over type aliases for object shapes
- Use generic constraints instead of type escapes

## Functional Programming Patterns

- **Guard statements**: Use early returns, no nested if/else
- **Pure functions**: No side effects in transformations
- **Immutable patterns**: Don't mutate inputs
- **Small functions**: Single responsibility
- **Explicit errors**: Throw meaningful errors, don't fail silently
- **Constants over functions**: `const VALUE = x` not `const getValue = () => x`
- **Logical operators**: Use `||` for fallbacks, not if statements

## Component Structure

```
component-name/
├── index.svelte # Main component
├── {name}.ts # Pure functions, types
├── {name}.svelte.ts # Svelte lifecycle functions
└── {sub}.svelte # Sub-components
```

## Formatting Rules (Prettier)

- Print width: 80
- Tab width: 2 spaces
- Single quotes
- Semicolons: always
- Trailing comma: all
- Bracket spacing: true

## CSS/Styling

- Use TailwindCSS utilities first
- PostCSS for custom styles
- Holocene design system components
- Avoid inline styles
- Use CSS variables from theme

## Comments and Documentation

- NO code comments unless explicitly requested
- Use descriptive variable/function names instead
- TypeScript types serve as documentation
- Component props should be self-documenting

## Error Handling

- Use Zod for validation
- Handle errors at component level
- Show user-friendly error messages
- Use toast notifications for async operations
- Implement proper loading states

## Accessibility

- Semantic HTML elements
- Proper ARIA attributes
- Keyboard navigation support
- Screen reader compatibility
- Color contrast compliance
112 changes: 112 additions & 0 deletions .serena/memories/holocene_design_system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# Holocene Design System

## Overview

Holocene is Temporal UI's custom design system built with Svelte 5 and TailwindCSS. It provides a consistent set of components following Temporal's design language.

## Core Components

### Layout Components

- **Card**: Content container with optional header/footer
- **Panel**: Side panel for additional content
- **Modal**: Overlay dialogs
- **Accordion**: Collapsible content sections
- **Tabs**: Tabbed navigation
- **VerticalNav**: Vertical navigation with animated backgrounds

### Form Components

- **Input**: Text input with validation
- **Select**: Dropdown selection
- **Checkbox**: Boolean selection
- **Radio**: Single choice selection
- **Toggle**: On/off switch
- **DatePicker**: Date selection
- **Combobox**: Searchable dropdown

### Data Display

- **Table**: Data tables with sorting/filtering
- **DataTable**: Advanced table with pagination
- **CodeBlock**: Syntax-highlighted code display
- **Badge**: Status indicators
- **Chip**: Tag/label display
- **EmptyState**: No data states

### Navigation

- **Button**: Primary interactive element
- **Link**: Navigation links
- **Breadcrumb**: Navigation hierarchy
- **Pagination**: Page navigation
- **TabList/TabPanel**: Tab navigation

### Feedback

- **Alert**: Information messages
- **Toast**: Temporary notifications
- **Loading**: Loading indicators
- **Skeleton**: Content placeholders
- **Tooltip**: Contextual help

## Component Structure

```typescript
// Standard component pattern
<script lang="ts">
import type { HTMLAttributes } from 'svelte/elements';

interface Props extends HTMLAttributes<HTMLElement> {
variant?: 'primary' | 'secondary';
class?: string;
}

let {
variant = 'primary',
class: className = '',
...restProps
}: Props = $props();
</script>

<div class={merge('base-styles', variantStyles[variant], className)} {...restProps}>
<!-- content -->
</div>
```

## Design Tokens

- Colors: Uses Tailwind color palette
- Spacing: 4px base unit (0.5, 1, 2, 4, 8, etc.)
- Typography: System font stack
- Shadows: Tailwind shadow utilities
- Borders: 1px default, rounded corners

## Best Practices

1. Always use Holocene components when available
2. Follow existing component patterns
3. Use TailwindCSS utilities for styling
4. Maintain consistent spacing
5. Ensure keyboard accessibility
6. Include ARIA attributes
7. Support dark/light themes
8. Test in Storybook

## Creating New Components

1. Place in `src/lib/holocene/component-name/`
2. Export from `index.svelte`
3. Add Storybook story
4. Follow naming conventions
5. Include TypeScript types
6. Support standard HTML attributes
7. Use `twMerge` for class merging

## Common Utilities

- `twMerge`: Merge Tailwind classes
- `formatDate`: Date formatting
- `translate`: i18n translations
- `getContext/setContext`: Component communication
- `createEventDispatcher`: Custom events
42 changes: 42 additions & 0 deletions .serena/memories/project_overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# Temporal UI Project Overview

## Purpose

Temporal UI is a web-based interface for the Temporal workflow orchestration platform. It provides a visual interface for managing and monitoring Temporal workflows, activities, namespaces, and other Temporal resources.

## Tech Stack

- **Framework**: SvelteKit with Svelte 5
- **Language**: TypeScript
- **Styling**: TailwindCSS + PostCSS
- **Design System**: Holocene (custom component library)
- **Build Tool**: Vite
- **Package Manager**: pnpm (>=8.6.0)
- **Node Version**: >=18.15.0
- **Testing**: Vitest (unit), Playwright (e2e/integration), Storybook (components)
- **Code Quality**: ESLint, Prettier, Stylelint, svelte-check
- **Forms**: SuperForms with Zod validation
- **State Management**: Svelte stores and runes

## Key Features

- Workflow execution monitoring and management
- Namespace management
- Search attributes configuration
- Activity tracking
- Real-time updates
- Multi-language support (i18n)

## Development Modes

- `dev`: Local development with UI server
- `dev:temporal-cli`: Development with Temporal CLI
- `dev:docker`: Development against Docker Compose Temporal
- `dev:local-temporal`: Development with local Temporal server

## Architecture

- Server-side rendering with SvelteKit
- Type-safe API calls using generated TypeScript types
- Responsive design with mobile support
- Modular component architecture using Holocene design system
85 changes: 85 additions & 0 deletions .serena/memories/project_structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Temporal UI Project Structure

## Root Directory

```
/Users/ross/code/ui/
├── src/ # Source code
├── tests/ # E2E and integration tests
├── static/ # Static assets
├── server/ # UI server build output
├── build/ # Build output
├── dist/ # Distribution files
├── node_modules/ # Dependencies
├── .storybook/ # Storybook configuration
├── scripts/ # Build and utility scripts
├── temporal/ # Temporal API protos (git submodule)
└── docs/ # Documentation

## Source Structure
src/
├── app.css # Global styles
├── app.html # HTML template
├── app.d.ts # Global TypeScript types
├── hooks.server.ts # SvelteKit server hooks
├── lib/ # Library code
│ ├── components/ # Reusable components
│ ├── holocene/ # Design system components
│ ├── services/ # API and business logic
│ ├── stores/ # Svelte stores
│ ├── types/ # TypeScript type definitions
│ ├── utilities/ # Helper functions
│ ├── i18n/ # Internationalization
│ ├── theme/ # Theme configuration
│ └── vendor/ # Third-party integrations
├── routes/ # SvelteKit routes
│ ├── (app)/ # Main app routes
│ ├── (auth)/ # Auth-related routes
│ └── api/ # API routes
└── fixtures/ # Test fixtures

## Key Directories

### Holocene Design System
src/lib/holocene/
- Alert, Button, Card, Modal components
- Form controls (Input, Select, Checkbox)
- Navigation (Tabs, VerticalNav)
- Data display (Table, CodeBlock)
- Layout components

### Routes Organization
src/routes/(app)/
├── namespaces/ # Namespace management
├── workflows/ # Workflow listing and details
├── schedules/ # Schedule management
├── batch-operations/ # Batch operations
└── nexus/ # Nexus endpoints

### Component Patterns
- Route-specific: `routes/.../\_components/`
- Reusable: `lib/components/`
- Design system: `lib/holocene/`

## Configuration Files
- `vite.config.ts` - Vite configuration
- `svelte.config.js` - SvelteKit configuration
- `tailwind.config.ts` - TailwindCSS configuration
- `tsconfig.json` - TypeScript configuration
- `.env.*` - Environment configurations
- `playwright.config.ts` - E2E test configuration
- `vitest.config.ts` - Unit test configuration

## Build Outputs
- `dist/` - Local build output
- `server/ui/assets/` - UI server assets
- `.svelte-kit/` - SvelteKit build cache
- `build/` - Production build

## Important Files
- `CLAUDE.md` - AI assistant instructions
- `package.json` - Dependencies and scripts
- `.prettierrc` - Code formatting rules
- `.eslintrc.cjs` - Linting rules
- `.stylelintrc` - CSS linting rules
```
Loading
Loading