bea-edit/agents.md

Project Agent Guide

Project overview

This repository contains juri-merger, a German-language SvelteKit application whose current UI is branded as beA-Edit. The main route lets users select or drag ZIP files in the browser. It currently displays the selected filenames; no server-side upload or archive-processing flow is present in this version.

The application also contains German legal pages for the imprint and privacy policy.

Technology stack

• SvelteKit 2
• Svelte 5 with runes mode forced for project source files
• TypeScript with strict mode
• Vite 8
• Tailwind CSS 4 through @tailwindcss/vite
• Skeleton 4 with a custom nominandum theme
• pnpm and pnpm-lock.yaml
• @sveltejs/adapter-auto
• Prettier with the Svelte and Tailwind plugins

Use pnpm, not npm or yarn, when installing packages or running project scripts.

Commands

pnpm install             # Install dependencies
pnpm dev                 # Start the development server
pnpm build               # Create a production build
pnpm preview             # Preview the production build
pnpm check               # Run Svelte and TypeScript diagnostics
pnpm check:watch         # Run diagnostics in watch mode
pnpm lint                # Check formatting with Prettier
pnpm format              # Format the repository with Prettier

There is currently no automated unit or end-to-end test suite. For code changes, run at least:

pnpm check
pnpm lint
pnpm build

If pre-existing warnings remain outside the files being changed, report them rather than making unrelated edits.

Repository structure

src/
├── app.html                         # German document shell and Skeleton theme selection
├── app.d.ts                         # SvelteKit application type declarations
├── lib/
│   ├── assets/                      # Bundled favicon and Nunito font files
│   ├── components/                  # Reusable Svelte components
│   │   ├── Button.svelte
│   │   ├── Card.svelte
│   │   └── ZipDropzone.svelte
│   ├── index.ts                     # Public `$lib` exports
│   └── nom-theme.css                # Custom Skeleton theme tokens
└── routes/
    ├── +layout.svelte               # Shared logo header and branded footer
    ├── +page.svelte                 # Main ZIP-selection page
    ├── layout.css                   # Tailwind/Skeleton imports and global font setup
    ├── datenschutz/+page.svelte     # Privacy policy
    └── impressum/+page.svelte       # Imprint
static/                              # Files served unchanged from the site root

Generated directories such as .svelte-kit/, build/, and node_modules/ must not be edited or committed.

Svelte conventions

• Use Svelte 5 runes and current event syntax. Prefer $props(), $state, $derived, snippets, {@render ...}, and handlers such as onclick over legacy APIs.
• Keep component scripts typed with <script lang="ts">.
• Define a local Props type for non-trivial component props.
• Use callback props for child-to-parent communication, as ZipDropzone.svelte does with onFilesSelected.
• Use $lib/... for imports from src/lib rather than long relative paths.
• Name reusable component files in PascalCase and route files according to SvelteKit conventions.
• Keep browser-only APIs such as File, FileList, and drag-and-drop handling in components that execute in the browser. Do not introduce server-side upload behavior unless requested.
• Preserve semantic HTML. Interactive drop zones must remain keyboard-operable buttons with an accessible name.

The Vite configuration forces runes mode for application files, so do not add legacy Svelte component patterns.

Styling conventions

Use Tailwind utility classes in Svelte markup for component and route styling. Orient new work around the existing classes in +layout.svelte, +page.svelte, Card.svelte, and ZipDropzone.svelte.

• Prefer existing theme utilities such as bg-primary-50, text-primary-900, border-primary-500, and rounded-container.
• Use the custom primary, secondary, tertiary, and surface scales defined in src/lib/nom-theme.css instead of adding arbitrary brand colors.
• Keep the established visual language: cool blue-gray page background, white cards, dark blue headings, subtle shadows, rounded containers, and the Nunito typeface.
• Use responsive Tailwind variants and ensure layouts work on narrow screens.
• Prefer utilities over new component-level <style> blocks or inline styles. Add global CSS only when defining shared theme primitives, imports, font faces, or behavior that cannot reasonably be expressed with utilities.
• Tailwind 4 is configured through Vite and src/routes/layout.css; there is no tailwind.config file.
• Keep complete utility class names visible to Tailwind. For variants, map each state to complete class strings rather than constructing fragments such as text-${color}.
• Preserve clear focus states, adequate contrast, and visible drag-and-drop feedback.

src/app.html applies data-theme="nominandum". Theme-level changes belong in src/lib/nom-theme.css; global Tailwind and Skeleton imports belong in src/routes/layout.css.

Formatting

Follow the checked-in Prettier configuration:

• Tabs for indentation
• Single quotes in scripts and styles where supported
• No trailing commas
• 100-character print width
• Svelte-aware and Tailwind-aware formatting

Use pnpm exec prettier --write <changed-files> for targeted formatting. Avoid formatting unrelated files solely to clean up existing differences.

Product and content constraints

• User-facing copy is German unless a task explicitly requests another language.
• Preserve legal text in datenschutz/+page.svelte and impressum/+page.svelte unless the request explicitly asks for content changes.
• Keep the shared Nominandum logo, footer artwork, and theme consistent across routes.
• ZIP selection is client-side and accepts .zip, application/zip, and application/x-zip-compressed files.
• Resetting the file input after selection is intentional so the same archive can be selected twice.
• Do not add network requests, file uploads, analytics, or persistence without an explicit requirement.

Change discipline

• Keep changes scoped to the request and preserve unrelated work, including untracked files.
• Inspect existing components and theme tokens before introducing new abstractions.
• Do not hand-edit generated output or lockfile contents. Update the lockfile only through pnpm when dependency changes are required.
• Avoid adding dependencies when the task can be completed with Svelte, browser APIs, Tailwind, or existing Skeleton packages.
• After implementation, review the changed files, run the relevant checks, and mention any remaining warnings or limitations.