From f909ab2a8dc36ba0f8a1cfe531de416397703bed Mon Sep 17 00:00:00 2001 From: Simon Axelsson Date: Wed, 16 Sep 2026 13:42:52 +0200 Subject: [PATCH] docs: add Digital Twin Specification for website analysis and reproduction Adds comprehensive specification document at docs/spec/DIGITAL-TWIN-SPEC.md covering: - Taxonomy of all website components (design, layout, UI components, pages, functionality, data, infrastructure, i18n) - Ontology: entity types, attributes, relationships - Topology: DOM, CSS spatial, visual hierarchy, responsive breakpoints - Media capture: images, video, icons, fonts, documents - Data collection: text, structured data, URLs, metadata - Functional specification: behavior, state machines, API contracts - Design system discovery and analysis - AI agent architecture (4 phases: Discovery, Analysis, Synthesis, Verification) - Quality criteria (completeness, accuracy, machine-readability) - Output format and file structure (c0py-output/ schema) - Agent contracts, parallelization, error handling Also updates AGENTS.md and README.md to reference the spec. Covers 14 major sections with detailed subsections for each component category found on any modern website or product. Co-commit with c0py repo on Gitea. --- AGENTS.md | 1 + README.md | 1 + docs/spec/DIGITAL-TWIN-SPEC.md | 1167 ++++++++++++++++++++++++++++++++ 3 files changed, 1169 insertions(+) create mode 100644 docs/spec/DIGITAL-TWIN-SPEC.md diff --git a/AGENTS.md b/AGENTS.md index b8c7888..bab30a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,7 @@ - API-kontrakt: `contracts/openapi.yaml` - Schema-versionshantering: semantisk versionering i `packages/types` +- Digital Twin Spec: `docs/spec/DIGITAL-TWIN-SPEC.md` (fullständig specifikation för webbplats-analys och identisk reproduktion) ## Fällor diff --git a/README.md b/README.md index 9b0e569..92c5c7a 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ apps/web/ → Next.js UI — registerhantering, dashboard, visualiserin packages/c0py-core → crawling, registry-uppbyggnad, analysmotor packages/config → Zod-validerad env-laddare packages/types → delade TypeScript-typer +docs/spec/ → Digital Twin Spec (webbplats-analys och reproduktion) ``` ## Konsumerade kapabiliteter diff --git a/docs/spec/DIGITAL-TWIN-SPEC.md b/docs/spec/DIGITAL-TWIN-SPEC.md new file mode 100644 index 0000000..b8d516c --- /dev/null +++ b/docs/spec/DIGITAL-TWIN-SPEC.md @@ -0,0 +1,1167 @@ +# C0PY — Digital Twin Specification + +**Version**: 0.1.0-draft +**Status**: Draft +**Purpose**: Specifies every category of component, data, and relationship that C0PY must capture from a website/product to produce a theoretically identical digital twin — reproducible by autonomous AI agents with full pixel-level fidelity and all functionality. + +--- + +## Innehållsförteckning + +1. [Översikt](#1-översikt) +2. [Definitioner](#2-definitioner) +3. [Taxonomi — Kategorier av beståndsdelar](#3-taxonomi) +4. [Ontologi — Entiteter, attribut, relationer](#4-ontologi) +5. [Topologi — Strukturella och rymsliga relationer](#5-topologi) +6. [Designinfångning](#6-designinfångning) +7. [Medieinfångning](#7-medieinfångning) +8. [Datainsamling](#8-datainsamling) +9. [Funktionsspecifikation](#9-funktionsspecifikation) +10. [Teknisk infrastruktur](#10-teknisk-infrastruktur) +11. [Tillgänglighet och internationisering](#11-tillgänglighet-och-internationalisering) +12. [Utdataformat](#12-utdataformat) +13. [AI-Agent-arkitektur](#13-ai-agent-arkitektur) +14. [Kvalitetskriterier](#14-kvalitetskriterier) + +--- + +## 1. Översikt + +C0PY är ett verktyg som konsumerar en webbadress och producerar ett fullständigt register — en **digital tvilling** — av webbplatsen. Tvillingen måste teoretiskt kunna återskapa **varje funktion**, **variabel utseende**, **alla data** och **alla komponenter** i identisk form. + +### Filosofi + +- **Heltäckande**: Ingen kategori av beståndsdel får förbisetas. +- **Automatiserad**: All infångning utförs av AI-agenter, inte manuellt. +- **Maskinläsbar utdata**: Allt produceras i strukturerat format (JSON/YAML + mediafiler). +- **Pixelnär**: Design ska beskrivas så exakt att en identisk kopia kan produceras. +- **Funktionellt hela**: All interaktivitet,状态, och beteende ska dokumenteras. + +### Scope + +Applicerar på: +- Webbplatser (singelpage, multipage, SPA, MPA) +- Webbsidor (lanseringssidor, produktsidor, bloggar) +- Webbservrar (REST, GraphQL, tider) +- SaaS-gränssnitt (dashboards, admin-paneler) +- E-handel (kataloger, kassaflöden, betalningar) +- Portaler (intranät, kundportaler, operatörsgränssnitt) + +--- + +## 2. Definitioner + +| Term | Definition | +|---|---| +| **Källa** | Den ursprungliga webbplatsen som ska analyseras | +| **Digital tvilling** | C0PYs fullständiga register av källan | +| **Agent** | En autonom AI-enhet som utför en specifik infångningsuppgift | +| **Taxonomi** | Klassificeringssystem för alla beståndsdelar | +| **Ontologi** | Entiteter, deras attribut och relationer | +| **Topologi** | Rumsliga och strukturella samband | +| **Komponent** | Återkommande UI-enhet med definierat beteende | +| **Mall** | Färdig struktur för en komponenttyp med plats för data | +| **Designtoken** | Grundläggande designenhet (färg, typografi, spacing) | +| **Yta** | Visuellt element som användaren ser och interagerar med | +| **Beteende** | Dynamisk respons på händelser eller tillstånd | +| **Dataobjekt** | Strukturerad information som visas eller bearbetas | +| **Tillstånd** | Aktuellt värde på en variabel vid en given tidpunkt | + +--- + +## 3. Taxonomi — Kategorier av beståndsdelar + +### 3.1 Ytliga designelement (Visual Design Layer) + +``` +design/ +├── colors/ +│ ├── semantic/ (primary, secondary, accent, error, success, warning, info) +│ ├── literal/ (#RRGGBB, rgb, hsl, named) +│ ├── transient/ (hover, active, focus, disabled, visited states) +│ ├── gradients/ (linear, radial, conic — positions, stops) +│ └── opacity/ (alpha values, overlay layers) +├── typography/ +│ ├── font-families/ (name, weight, style, source, fallback) +│ ├── type-scale/ (h1-h6, body, caption, overline, monospace) +│ ├── letter-spacing/ (per element type) +│ ├── line-height/ (per element type) +│ └── text-decoration/ (underline, line-through, styles) +├── spacing/ +│ ├── padding/ (per component, per breakpoint) +│ ├── margin/ (per component, per breakpoint) +│ ├── gap/ (grid/flex gap values) +│ └── inset/ (inset properties) +├── borders/ +│ ├── width/ +│ ├── style/ (solid, dashed, dotted, double, groove) +│ ├── color/ +│ └── radius/ (per corner, per component) +├── shadows/ +│ ├── box-shadow/ (layered, per elevation level) +│ └── text-shadow/ +├── backgrounds/ +│ ├── color/ +│ ├── image/ (url, size, repeat, position, attachment) +│ ├── pattern/ (repeating patterns, textures) +│ └── gradient/ +└── animations/ + ├── keyframes/ (name, duration, easing, delay, iteration) + ├── transitions/ (property, duration, easing, delay) + └── scroll-effects/ (parallax, sticky, reveal) +``` + +### 3.2 Layout och struktur (Layout Layer) + +``` +layout/ +├── grid-system/ +│ ├── columns/ (count, width, offset) +│ ├── rows/ (height, min/max) +│ ├── gaps/ (row-gap, column-gap) +│ └── responsive-breakpoints/ (width, orientation, media-query) +├── containers/ +│ ├── max-width/ (per breakpoint) +│ ├── padding/ (per side, per breakpoint) +│ └── margin/ (auto, fixed, percentage) +├── flex-configurations/ (direction, justify, align, wrap, gap) +├── position-scheme/ (static, relative, absolute, fixed, sticky) +│ └── z-index-stack/ (layer ordering) +├── aspect-ratios/ (per media/container) +└── overflow/ (visible, hidden, scroll, auto) +``` + +### 3.3 Komponenter (Component Layer) + +``` +components/ +├── navigation/ +│ ├── primary-menu/ (items, order, dropdowns, mega-menus) +│ ├── secondary-menu/ +│ ├── breadcrumbs/ (items, separators, current indicator) +│ ├── pagination/ (pages, current, prev/next, size) +│ ├── tabs/ (labels, panels, active state) +│ ├── sidebar/ (sections, collapsible, sticky) +│ └── footer/ (columns, links, social, legal) +├── forms/ +│ ├── input/ (type, placeholder, validation, size) +│ ├── textarea/ (rows, maxlength, resize) +│ ├── select/ (options, multi, search, grouped) +│ ├── checkbox/ (label, checked, indeterminate, disabled) +│ ├── radio/ (label, selected, group) +│ ├── toggle/ (on/off, label, track, thumb) +│ ├── slider/ (min, max, step, value, range) +│ ├── date-picker/ (format, range, calendar style) +│ ├── file-upload/ (accept, multiple, drag-drop, preview) +│ ├── search/ (input, results, autocomplete, filters) +│ ├── button/ (label, variant, size, icon, loading state) +│ └── form-layout/ (labels, order, sections, help text) +├── feedback/ +│ ├── toast/ (message, type, duration, position) +│ ├── snackbar/ +│ ├── alert/ (type, icon, dismissable, actions) +│ ├── modal/ (title, content, actions, size, backdrop) +│ ├── dialog/ (form, confirm, info, progress) +│ ├── tooltip/ (content, position, delay) +│ ├── popover/ (content, position, trigger) +│ ├── dropdown/ (options, trigger, search) +│ └── loading/ (spinners, skeletons, progress bars) +├── content/ +│ ├── card/ (image, title, subtitle, content, actions) +│ ├── list/ (ordered, unordered, definition, media) +│ ├── table/ (columns, rows, sort, filter, pagination, expand) +│ ├── gallery/ (images, captions, grid, lightbox) +│ ├── media-player/ (video, audio, controls, captions, quality) +│ ├── accordion/ (sections, expanded, animation) +│ ├── timeline/ (events, connectors, orientation) +│ └── tag/ (label, color, removable, count) +├── display/ +│ ├── heading/ (level, align, decoration) +│ ├── paragraph/ (align, indent, spacing) +│ ├── quote/ (text, attribution, style) +│ ├── code/ (language, copy, theme, line-numbers) +│ ├── badge/ (text, color, size, shape) +│ ├── stat/ (value, label, trend, format) +│ └── avatar/ (image, initials, size, shape, status) +└── data/ + ├── chart/ (type, data, axes, legend, tooltip, animation) + ├── graph/ (nodes, edges, layout, interactive) + ├── map/ (provider, bounds, markers, layers, controls) + ├── calendar/ (date range, events, view, selectable) + └── tree/ (nodes, expand, select, checkbox) +``` + +### 3.4 Sidstrukturer (Page Structure Layer) + +``` +pages/ +├── landing-page/ (hero, features, testimonials, pricing, CTA, stats) +├── product-page/ (gallery, description, specs, reviews, related, buy) +├── category-page/ (filters, grid/list, sort, pagination, count) +├── checkout-flow/ (steps, forms, summary, payment, confirm) +├── dashboard/ (widgets, charts, tables, filters, time-range) +├── login-page/ (form, oauth, forgot, register, mfa) +├── profile-page/ (avatar, info, preferences, security, activity) +├── settings-page/ (sections, toggles, forms, save/cancel) +├── search-results/ (query, filters, sort, results, count, pagination) +├── error-pages/ (404, 500, 403, 401 — design, message, actions) +├── legal/ (terms, privacy, cookies, accessibility) +└── blog/ (post, listing, category, tag, author, comments) +``` + +### 3.5 Funktionella element (Functional Layer) + +``` +functionality/ +├── routing/ +│ ├── url-patterns/ (path, params, query, hash, canonical) +│ ├── redirects/ (from, to, type, condition) +│ ├── 404/ (design, message, search, suggestions) +│ └── deep-linking/ (shareable, restoreable, bookmarkable) +├── state-management/ +│ ├── global-state/ (store, slices, selectors, middleware) +│ ├── local-state/ (component-level, persistence) +│ ├── session-state/ (auth, cart, preferences) +│ └── URL-state/ (query params, hash fragments) +├── API/ +│ ├── endpoints/ (method, path, params, body, response) +│ ├── graphql-schema/ (types, queries, mutations, subscriptions) +│ ├── websockets/ (channels, messages, auth, reconnection) +│ └── SSE/ (events, retry, data format) +├── events/ +│ ├── user-interaction/ (click, hover, focus, blur, submit, scroll) +│ ├── lifecycle/ (mount, unmount, update, create, delete) +│ ├── network/ (online, offline, reconnect) +│ └── custom/ (domain events, bus events) +├── validation/ +│ ├── client/ (format, required, range, custom) +│ ├── server/ (schema, auth, permission, business rules) +│ └── error-format/ (code, message, field, retryable) +└── workflows/ + ├── multi-step/ (steps, current, status, guard, redirect) + ├── approval/ (requester, approver, levels, evidence) + └── queued/ (job type, status, retry, dead-letter) +``` + +### 3.6 Dataobjekt (Data Layer) + +``` +data/ +├── content/ +│ ├── text/ (all visible text, language, region, variant) +│ ├── image-alt/ (alt text for every image) +│ ├── link-text/ (anchor text, title, description) +│ └── metadata/ (title, description, keywords, OG, Twitter) +├── structured/ +│ ├── products/ (name, price, currency, sku, stock, attributes) +│ ├── orders/ (id, items, totals, status, customer, dates) +│ ├── users/ (name, email, role, profile, preferences) +│ ├── articles/ (title, body, author, date, tags, category) +│ └── settings/ (key, value, type, scope, updated) +├── relationships/ +│ ├── parent-child/ +│ ├── many-to-many/ +│ ├── referral/ (who links to whom, anchor) +│ └── dependency/ (what depends on what) +└── temporal/ + ├── created/ (timestamp, actor, source) + ├── modified/ (timestamp, actor, field, previous) + └── deleted/ (soft-delete timestamp, actor, reason) +``` + +### 3.7 Teknisk infrastruktur (Infrastructure Layer) + +``` +infrastructure/ +├── stack/ +│ ├── framework/ (React, Next, Vue, etc. + version) +│ ├── runtime/ (Node, Python, Go + version) +│ ├── build/ (tool, config, output) +│ ├── server/ (Caddy, Nginx, Apache, Cloudflare) +│ └── database/ (Postgres, MySQL, Mongo, Redis + version) +├── performance/ +│ ├── bundle-analysis/ (size, chunks, dedup, lazy loading) +│ ├── lighthouse/ (PWA, accessibility, SEO, performance scores) +│ ├── core-web-vitals/ (FCP, LCP, INP, CLS, TTFB) +│ └── budget/ (max size, max load time per asset) +├── security/ +│ ├── headers/ (CSP, HSTS, X-Frame, X-Content-Type) +│ ├── auth/ (method, flow, tokens, refresh, expiry) +│ ├── cors/ (origins, methods, headers, credentials) +│ └── rate-limiting/ (rules, headers, response) +└── deployment/ + ├── ci/ (pipelines, triggers, environments) + ├── cd/ (strategies, rollbacks, health checks) + └── monitoring/ (errors, performance, uptime, alerts) +``` + +--- + +## 4. Ontologi — Entiteter, attribut, relationer + +### 4.1 Entitetstyper + +| Entitet | Supertyp | Sekundära typer | +|---|---|---| +| **Color** | design_token | semantic, literal, transient, opacity, gradient | +| **Typography** | design_token | font_scale, type_scale, text_style | +| **Spacing** | design_token | padding, margin, gap, inset | +| **Border** | design_token | width, style, color, radius | +| **Shadow** | design_token | box_shadow, text_shadow | +| **Animation** | design_token | keyframe, transition, effect | +| **Component** | ui_element | container, content, feedback, navigation, data | +| **Page** | layout | landing, product, dashboard, login, error | +| **Section** | page_part | hero, features, testimonials, pricing, CTA | +| **Template** | structural | grid, flex, absolute, responsive | +| **DataObject** | content | text, image, structured, temporal | +| **Route** | functionality | static, dynamic, parameter, redirect | +| **Event** | behavior | user, lifecycle, network, custom | +| **API** | endpoint | REST, GraphQL, WebSocket, SSE | +| **Breakpoint** | responsive | mobile, tablet, desktop, wide | +| **MediaAsset** | resource | image, video, audio, font, icon, document | +| **DesignSystem** | collection | tokens, components, patterns, guidelines | +| **State** | variable | global, local, session, URL | +| **Workflow** | process | linear, branching, parallel, conditional | +| **ValidationRule** | constraint | client, server, format, range, custom | + +### 4.2 attribut per entitet (utvalda exempel) + +**Color:** +``` +id: uuid +name: string (semantic_name or hex) +value: string (hex/rgb/hsl/named) +alpha: float (0-1, optional) +type: enum (semantic|literal|transient|opacity|gradient) +state: enum (default|hover|active|focus|disabled|visited) +usedBy: [Component.id] +contrastRatio: float +wcagLevel: enum (AA|AAA|pass|fail) +``` + +**Component:** +``` +id: uuid +type: enum (navigation|form|feedback|content|data|display) +name: string (e.g., "primary-menu", "checkout-modal") +props: JSON (all configurable properties and defaults) +state: JSON (current state values) +styles: { colors, typography, spacing, borders, shadows } +behavior: { events, handlers, transitions } +data: { source, mapping, refresh, caching } +accessibility: { aria, roles, keyboard, focus } +responsive: { breakpoints, adaptations } +composition: [Component.id] (nested components) +parent: Component.id | Page.id +order: int +visibility: { condition, permission, featureFlag } +``` + +**Page:** +``` +id: uuid +url: string +title: string +template: string (layout template name) +sections: [Section.id] (ordered) +components: [Component.id] +meta: { seo, og, twitter, jsonld } +scripts: [{src, async, defer, type}] +styles: [{src, inline, media}] +state: { initial, persisted } +error: { type, design, actions } +i18n: { locale, fallback, rtl } +``` + +### 4.3 Relationer + +``` +Composition (strong): + Page ──contains──> Section + Section ──contains──> Component + Component ──contains──> Component + Component ──renders──> DataObject + +Reference (weak): + Component ──uses──> Color + Component ──uses──> Typography + Component ──uses──> Spacing + Component ──uses──> Border + Component ──uses──> Shadow + Component ──uses──> Animation + Component ──validates──> ValidationRule + Component ──subscribes──> Event + API ──returns──> DataObject + Route ──maps──> Page + +Dependency: + Component ──depends──> Component (loading order) + Page ──depends──> MediaAsset + Component ──requires──> State + Workflow ──includes──> Event + +Event-Handling: + Event ──triggers──> Handler + Handler ──modifies──> State + Handler ──calls──> API + Handler ──navigates──> Route + Handler ──renders──> Component (conditional) + +Temporal: + DataObject ──createdBy──> Actor + DataObject ──modifiedBy──> Actor + DataObject ──versionOf──> DataObject (previous) +``` + +--- + +## 5. Topologi — Strukturella och rymsliga relationer + +### 5.1 DOM-topologi + +``` +root (document) +├── head +│ ├── meta [n] +│ ├── title +│ ├── link [n] (stylesheets, icons, preload) +│ ├── script [n] +│ └── style [n] +└── body + ├── header (semantic) | [optional] + │ ├── nav.primary + │ ├── nav.secondary + │ └── brand/logo + ├── main + │ ├── section.hero | [optional] + │ ├── section.features | [optional] + │ ├── section.content | [repeating] + │ ├── section.sidebar | [optional] + │ └── section.footer | [optional] + │ ├── component [n] + │ └── component [n] + ├── aside | [optional] + │ └── component [n] + └── footer + ├── nav [n] + └── component [n] +``` + +### 5.2 CSS-rumslig topologi + +``` +viewport +├── block flow (vertical stacking) +│ ├── margin (outside) +│ │ └── border +│ │ └── padding (inside) +│ │ └── content +│ └── inline flow (horizontal) +│ └── flex/grid container +│ └── items [n] +├── position:absolute (removed from flow, positioned by top/right/bottom/left) +├── position:fixed (viewport-relative, persistent) +├── position:sticky (conditional flow + viewport-relative) +└── z-index-stack (layer ordering, paint order) +``` + +### 5.3 Visuell hierarki + +``` +elevation/stacking-context: + base (z: 0) + dropdown (z: 10) + sticky-header (z: 50) + modal-backdrop (z: 100) + modal-content (z: 101) + drawer (z: 200) + toast (z: 1000) + alert (z: 1001) + tooltip (z: 2000) + +visual-priority: + primary (largest, boldest, most contrast) + secondary (medium) + tertiary (smallest, subdued) + disabled (low contrast, reduced presence) +``` + +### 5.4 Reaktionsbild-topologi (Responsive) + +``` +breakpoints [n]: + mobile (max-width: 767px): + layout: single-column + navigation: hamburger/drawer + typography: scale-factor 0.85 + spacing: scale-factor 0.75 + images: responsive, srcset variants + tablet (768px–1023px): + layout: 2-column where applicable + navigation: expanded or hamburger + typography: scale-factor 0.95 + spacing: scale-factor 0.875 + desktop (1024px–1439px): + layout: full grid (e.g., 12-col) + navigation: full horizontal + typography: scale-factor 1.0 + spacing: base values + wide (min-width: 1440px): + layout: constrained-width centered + navigation: full + mega-menu + typography: scale-factor 1.05 + spacing: scale-factor 1.05 +``` + +--- + +## 6. Designinfångning + +### 6.1 Designsystemupptäckt + +Agenterna ska automatiskt upptäcka och definiera: + +**6.1.1 DesignToken-katalog** +``` +Per upptäckt: +- Token-name (conventionell, t.ex. "color-primary", "space-md") +- Token-värde (exakt, inklusive enhet) +- Token-typ (color, typography, spacing, border, shadow, animation) +- Token-status (draft, stable, deprecated) +- Token-beskrivning (varför existerar den, användning) +- Token-användning (var används den, hur ofta) +- Token-relaterade (varianter, delmängder, superord) +``` + +**6.1.2 Identifieringsmetod** +- Sortera designtokens efter frekvens (vad som förekommer mest) +- Identifiera primära (används > 5 ställen) → sekundära (2-4) → enskilda (1) +- Gröna (används > 10 ställen), gula (2-10), röda (1) — rekommenderar konsolidering +- Identifiera "utanför" variationer som eventuellt förväxlar systemet → flagga för granskning + +### 6.2 Automatisk designanalys + +``` +För varje sida: +1. Skanna all synlig UI (DOM + renderat) +2. Extrahera alla designtokens (färger, typografi, spacing, etc.) +3. Gruppera efter typ och namn +4. Identifiera inkonsekvenser (samma funktion, olika namn/värde) +5. Identifiera brist på system (varierad margin mellan liknande element) +6. Producera designtoken-katalog med förslag till standardisering +``` + +--- + +## 7. Medieinfångning + +### 7.1 Bilder + +``` +Per bild: +- src (ursprunglig url) +- formats: [jpeg, png, webp, avif, svg, gif, heic] +- dimensions: {width, height} (px) +- aspect-ratio: W:H +- alt-text (bildtext för tillgänglighet) +- srcset: [{width, url}, ...] (responsiva varianter) +- sizes: string (CSS sizes attribute) +- loading: enum (eager|lazy) +- decoding: enum (async|sync|auto) +- content-color: dominerande färg (för fade-in LCP) +- position: {page, section, component, order} +- crop: {type, focal-point-x, focal-point-y} +- background: {color-fallback} +- dpr-variants: [{dpr, url, dimensions}] +``` + +### 7.2 Video + +``` +Per video: +- src (primär url) +- formats: [mp4, webm, ogg] +- poster: {url, dimensions} +- dimensions: {width, height} +- aspect-ratio +- autoplay, muted, loop, controls, preload +- caption-tracks: [{src, language, kind, default}] +- chapters: [{start-time, label}] +- thumbnails: [{time, url}] +- lazy: boolean +- position: {page, section, component, order} +``` + +### 7.3 Ikonografie + +``` +Per ikon: +- name/label (tillägnad, beskrivande) +- format: [svg-png, icon-font, icon-library] +- dimensions: {width, height} (px, 16/20/24/32/48/64 etc.) +- color: {default, hover, active, disabled} +- weight: {regular, thin, bold, filled, outlined} +- library: [phosphor, heroicons, lucide, fontawesome, custom] +- glyph-id (och unicode om icon-font) +- position: {page, component, context} +- alternative-spellings: [synonyma varianter] +- aliasing: {duplicate-detection, canonical} +``` + +### 7.4 Typsnitt + +``` +Per typsnitt: +- family-name: string +- weight: [100-900, italic/normal] +- style: [normal, italic, oblique] +- unicode-range: string +- format: [woff2, woff, ttf, otf, eot] +- src: url +- font-display: [auto|block|swap|fallback|optional] +- variable: boolean (var font) +- axes: [{axis-tag, min, max, default}] +- subset: [latin, latin-ext, cyrillic, etc.] +- size-adjust: float (per fallbackskrift) +- ascent-override, descent-override: float +- unicode-range: string +- system-fallback: [font1, font2, ...] +``` + +### 7.5 Andra resurser + +``` +CSS/JS: +- src, type, media, async, defer, integrity, preload, prefetch + +Documents: +- PDF, DOCX, etc. — url, size, language, description + +Favicon/Manifest: +- manifest.json (name, short_name, icons, theme, orientation) +- apple-touch-icon, mask-icon, tile-image +- favicon.ico, favicon-16x16, favicon-32x32, etc. + +Fonts-in-use: +- All varianter som faktiskt används (detected via computed styles) +- Fallback chains per font-family +``` + +--- + +## 8. Datainsamling + +### 8.1 Innehållsinsamling + +``` +Per sida: +1. All synlig text (detekterad per element, i DOM-ordning) + - Språkidentifiering (ISO 639-1 per text-block) + - Texttyp (heading, body, caption, button, label, error) + - Kontext (var texten förekommer, vilken komponent) + - Längd (tecken, ord, rader) + - Variant (om flera varianter existerar, t.ex. A/B test) + +2. All bildtext (alt, title, src-set description) + +3. All länktext och mål + - Interna/externa + - Anchor text, title attribute + - Visa/skriv typ (icon, text, combined) + +4. Metadata + - page.title, page.description + - og:title, og:description, og:image + - twitter:card, twitter:title, twitter:description + - schema.org/JSON-LD (full structure) + - twitter:meta, fb:meta +``` + +### 8.2 Strukturerad datainsamling + +``` +Per dataobjekt: +- Schema (fält, typer, validering, relationalitet) +- Data (exemplen som faktiskt finns i produktion) +- API-källa (var data hämtas) +- Renderingssätt (direkt, kundtjänst, API, statisk) +- Cache-strategi (TTL, invalidation) +- Persistens (var och hur lagras) +- Behörighet (vem kan se, ändra, radera) +- Version (om det finns versionshantering) +``` + +### 8.3 URL-strukturinsamling + +``` +Per sida/endpoint: +- URL (fullständig, kanonical) +- Metod (GET, POST, PUT, DELETE, PATCH) +- Parameter (path, query, header, body) +- Response (status, body, headers, cache) +- Parameter-schema (namn, typ, required, default, validering) +- Auth-behov (anonymous, authenticated, role) +- Rate-limit (om tillämpligt) +- Relaterade URLs (prev, next, related, parent) +``` + +--- + +## 9. Funktionsspecifikation + +### 9.1 Beteende-specifikation + +För varje interaktiv element: + +``` +Element-specifikation: +- Trigger (händelse som orsakar förändring) +- Precondition (tillstånd krävs för att utlösas) +- Action (vad som händer) +- Effect (synlig förändring) +- Side-effect (API-anrop, navigation, tillståndsförändring) +- Error-path (vad händer vid fel) +- Loading-state (visas under bearbetning) +- Empty-state (visas när inget finns) +- Disabled-state (tillgänglighet vid inaktiv) +- Undo/Redo (om möjligt, återställningssätt) +- Keyboard-shortcut (tillgänglighet) +- Touch/Gesture (mobile interaktion) +``` + +### 9.2 Tillståndsmaskin-specifikation + +``` +Per tillståndsmaskin: +- States (namn, typ: idle, loading, success, error, empty, disabled) +- Transitions (from, to, trigger, guard, action) +- Initial state +- Final states (terminals) +- History (back/forward support) +- Persistence (session, localStorage, cookie) +``` + +### 9.3 API-kontraktsspecifikation + +``` +Per endpoint: +- Method +- URL (inklusive parametrar) +- Auth (Bearer, API-Key, OAuth, Session) +- Request (headers, body schema, query params, path params) +- Response (status codes, body schema, headers) +- Error format +- Idempotens (yes/no, key format) +- Rate limit (requests/minute, burst) +- Versioning (URL, header, query) +- Deprecation (if deprecated, since, removal date) +- Bearer format (JWT claims, token type, expiry) +``` + +--- + +## 10. Tillgänglighet och internationisering + +### 10.1 Tillgänglighet (WCAG) + +``` +Per sida/komponent: +- WCAG nivå (A, AA, AAA) +- ARIA-label (om tillämpligt) +- ARIA-roll (heading, navigation, main, alert, dialog, etc.) +- ARIA-status (live region, polite, assertive) +- Fokus-kort (tab order, visible focus) +- Tangentbordsnavigering (shortcuts, skip-links) +- Färg-kontrast (förhållande, nivå) +- Text-alternativ (bildtext, text-alternativ för video/audio) +- Flashing (seizure-säkerhet) +- Form-validering (error association, live regions) +``` + +### 10.2 Internationisering (i18n) + +``` +Språkdata: +- supported-locales: [locale-code, ...] +- default-locale +- rtl-locales: [locale-code, ...] +- Translations: {key: {locale: value, ...}, ...} +- Pluralization rules (per locale) +- Date/time format (per locale) +- Number/currency format (per locale, precision, separator) +- Address format (per locale, fields, order) +- Name format (per locale, order, titles) +- Direction: ltr | rtl | auto (per locale) +``` + +--- + +## 11. Utdataformat + +### 11.1 Katalogen Struktur + +Allt produceras i en katalog som är maskinläsbar och omfattande: + +``` +c0py-output/ +├── manifest.json (overgripande information om källan) +├── schema/ (ontologi, typer, relationer) +│ ├── entities.json (entitetstyper och attribut) +│ ├── relations.json (relationschema) +│ └── enums.json (uppräknade typer) +├── design/ (designsystem och tokens) +│ ├── tokens.json (alla designtokens) +│ ├── components.json (komponentspecifikation) +│ └── pages.json (sidstruktur) +├── media/ (nerladdade mediafiler) +│ ├── images/ (bilder med metadata) +│ ├── fonts/ (typsnittsfiler) +│ ├── icons/ (ikonfiler) +│ ├── videos/ (videofiler) +│ └── documents/ (dokumentfiler) +├── content/ (all text och data) +│ ├── text/ (textblock med metadata) +│ ├── data/ (strukturerad data) +│ └── metadata/ (SEO, OG, meta) +├── functionality/ (beteende och funktioner) +│ ├── routes.json (url-struktur) +│ ├── api.json (API-kontrakt) +│ ├── state.json (tillståndsmaskiner) +│ └── events.json (händelser och handläggare) +├── infrastructure/ (teknisk info) +│ ├── stack.json (teknikstack) +│ ├── security.json (säkerhetskonfiguration) +│ └── performance.json (prestanda data) +└── topology/ (rumsliga strukturer) + ├── dom.json (DOM-träd) + ├── css.json (CSS-struktur) + └── layout.json (layouttopologi) +``` + +### 11.2 Manifestformat + +```json +{ + "version": "0.1.0", + "source": "https://example.com", + "capturedAt": "2026-09-16T13:00:00Z", + "agentRunId": "uuid", + "pages": [ + { + "url": "/", + "title": "Home", + "status": 200, + "contentType": "text/html", + "depth": 0, + "discoveredAt": "...", + "sections": [...], + "components": [...], + "metadata": {...}, + "i18n": {...} + } + ], + "designTokens": [...], + "mediaAssets": [...], + "dataObjects": [...], + "apiEndpoints": [...], + "infrastructure": {...}, + "topology": {...}, + "statistics": { + "totalPages": 42, + "totalComponents": 312, + "totalMediaAssets": 158, + "totalTextBlocks": 1047, + "totalApiEndpoints": 24, + "totalDataObjects": 56, + "totalDesignTokens": 89, + "captureDuration": "PT2H30M" + } +} +``` + +### 11.3 Media-namnkonvention + +``` +media-{type}-{hash-originalname}.{ext} +t.ex. media-image-a3f8b2c1-hero-banner.webp +``` + +### 11.4 ID-konventioner + +Alla ID:er i dataset: +- UUID v4 för entiteter +- `[type]-[name]` för designtokens +- `[type]-[slug]` för sidor och komponenter +- Konsekvent i alla filer + +--- + +## 12. AI-Agent-arkitektur + +### 12.1 Övergripande arbetsflöde + +``` +Trigger: URL som anges av användaren + +Phase 1: DISCOVERY (Upptäckt) +├── Agent: SiteMapAgent +│ ├── Crawl alla sidor (djup-begränsad, breadth-first) +│ ├── Identifiera template-typer +│ ├── Identifiera unika komponenter +│ ├── Bygga URL-väg (alla upptäckta URL:er) +│ ├── Identifiera dynamiska rutter (parametriserade URL:er) +│ └── Producera sitemap.json +├── Agent: TechAgent +│ ├── Identifiera teknikstack (framework, runtime, server) +│ ├── Identifiera CDN, DNS, SSL config +│ ├── Identifiera build-tool, bundler, output +│ └── Producera infrastructure.json +└── Agent: DataAgent + ├── Identifiera API-endpoints (OpenAPI, Swagger, schema) + ├── Identifiera GraphQL schema (introspection) + ├── Identifiera dataobjekt och relationer + └── Producera api.json + data.json + +Phase 2: ANALYSIS (Analys) +├── Agent: DesignAgent +│ ├── Analysera färger → designtoken-katalog +│ ├── Analysera typografi → typografispecifikation +│ ├── Analysera spacing → spacing-specifikation +│ ├── Analysera komponenter → komponentspecifikation +│ ├── Identifiera designmönster → patterns +│ └── Producera design.json +├── Agent: ContentAgent +│ ├── Extrahera all text → content.json +│ ├── Extrahera all metadata → metadata.json +│ ├── Extrahera all data → data.json +│ └── Identifiera i18n → i18n.json +├── Agent: MediaAgent +│ ├── Hämta alla bilder (med format, storlek, metadata) +│ ├── Hämta alla ikoner (med format, storlek, stil) +│ ├── Hämta alla typsnitt (med format, format, källa) +│ ├── Hämta alla videor +│ └── Producera media-manifest + nerladda mediafiler +└── Agent: TopologyAgent + ├── Bygga DOM-träd → dom.json + ├── Analysera CSS → css.json + ├── Bygga layouttopologi → layout.json + └── Identifiera breakpoints → responsive.json + +Phase 3: SYNTHESIS (Syntes) +├── Agent: SpecAgent +│ ├── Samla alla analyser +│ ├── Identifiera inkonsekventer → spec-fynd +│ ├── Bygga komplett designsystem-specifikation +│ ├── Bygga komplett funktionsspecifikation +│ ├── Bygga komplett datamodell +│ └── Producera spec.json + spec.md +├── Agent: QualityAgent +│ ├── Validera fullständighet (saknade kategorier?) +│ ├── Kontrasträkning (WCAG-förhållande) +│ ├── Konsistenskoll (design-inkonsekvenser) +│ ├── Funktionsfullständighet (alla interaktioner registrerade?) +│ └── Producera kvalitetsrapport +└── Agent: AssemblyAgent + ├── Samla alla filer i utdata-katalog + ├── generera manifest.json + ├── validera ID-konventioner + ├── validera schema-konsekvens + └── Producera slutgiltig k0py-digitalt-vapen.zip + +Phase 4: VERIFICATION (Verifiering) +├── Agent: ReplayAgent +│ ├── Läsa in katalog +│ ├── Tillverka visuell representation (screenshot-mock) +│ ├── Jämför med källan (om tillgänglig) +│ ├── Identifiera luckor +│ └── Förbättra iteration (loop till As-II om nödvändig) +└── Agent: AuditAgent + ├── Kontrollera att inga kategorier saknas + ├── Kontrollera att alla ID är unika och konsekventa + └── Producera certifikat (eller förbättringsrekommendationer) +``` + +### 12.2 Agent-kontrakt + +```yaml +agent: + name: string + description: string + inputs: + - name: string + type: string + required: boolean + schema: JSONSchema + outputs: + - name: string + type: string + schema: JSONSchema + capabilities: + - crawl + - analyze + - synthesize + - verify + error-handling: + retry: {count, delay, backoff} + fallback: string + escalation: string + timeout: PT1H +``` + +### 12.3 Konkurrens och samordning + +- Phase 1-agenter körs parallellt (upptäckandet kan delas oberoende) +- Phase 2-agenter beror på Phase 1 och körs parallellt +- Phase 3-agenter beror på Phase 2 och körs sekventiellt (SpecAgent först) +- Phase 4 körs efter Phase 3 och kan trigga omloopning +- Alla agent-utdata skrivs till gemensam datalager med ID-baserad adressering +- Locking: ingen agent skriver till samma fil samtidigt + +### 12.4 Prompt-mall för agentspecifika uppgifter + +``` +Du är en C0PY-analysagent. Ditt uppdrag: + +MÅL: [specifikt mål] +KÄLLA: [url eller data] +OUTPUT_SCHEMA: [filnavn och schema] + +STRATEGI: +1. [Steg-för-steg beskrivning av analysmetod] +2. [Systematisk genomföring] + +VALIDERING: +- Kontrollera [kriterier] +- Varför [kriterier] +- Om [undantag] → [åtgärd] + +OUTPUT FORMAT: +[för detaljerad beskrivning av utdata] + +FÄLLOR ATT UNDVIKA: +- [Vanliga fel för denna analys] +- [Kännedom om webbplatser som är svåra att analysera] + +BESKRIV ALLT PÅ FÖRRA NIVÅ NÄR SOM HELST: +[Anvisningar om hur detaljerad beskrivningen ska vara] + +SLUTLIGEN, producera [filename.json]: +{schema} +``` + +--- + +## 13. Kvalitetskriterier + +### 13.1 Fullständighetskriterier + +``` +MINSTAKRA: +- Alla URL:er på källan upptäckta och beskrivna (inriktningsgrad > 99%) +- Alla synliga komponenter upptäckta och klassificerade (> 98%) +- Alla designtokens upptäckta och katalogiserade (> 95%) +- Alla mediafiler identifierade (> 95%, undantag: external CDN) +- Alla API-endpoints identifierade (> 90%) +- Alla dataobjekt identifierade (> 90%) +- Alla funktioner beskrivna (> 95%) +- Alla tillståndsmaskiner dokumenterade (> 90%) +- Tillgänglighetskrav kontrollerade för alla komponenter (100%) +``` + +### 13.2 Noggrannhetskriterier + +``` +DESIGN: +- Färgvärden: exakta (hex/rgb matchning 100%) +- Typografi: exakt (font, size, weight, line-height matchning 100%) +- Spacing: exakt (margin, padding matchning ±1px) +- Position: exakt (layout matchning ±1px) + +DATA: +- Text: ordagrunt exakt (källmatchning 100%) +- Strukturerad data: fält-namn och typer exakt +- API: statuskoder, parametrar, responsformat 100% + +FUNKTION: +- Event-handlers: fullständig uppräkning +- Tillståndsmaskiner: alla stater och övergångar +- Villkor: alla synliga/oscilla tillstånd dokumenterade +``` + +### 13.3 Maskinläsbarhetskriterier + +``` +- All utdata i giltig JSON/YAML +- Alla ID konsekventa och unika +- Alla referenser giltiga (ingen dubblett, ingen brygga) +- Schema-inre konsistens (inga spruckna referenser) +- Inga tvära avbrott i katalogstrukturen +- Varje entitet har minst: id, typ, namn, beskrivning +``` + +--- + +## 14. Gränssnitt och icke-funktionskrav + +### 14.1 Performance + +``` +- Crawling: maximalt 100 sidor/minut (respekterar robots.txt) +- Analys: maximalt 5 minuter per sida +- Total körning: maximalt 1 timme för upp till 500 sidor +- Agent timeout: 1 timme per agent +- Minnesanvändning: maximalt 4 GB per agent +``` + +### 14.2 Säkerhet + +``` +- Inga inmatade secrets ska lagras eller loggas +- Alla media hämtas via autentiserade kanaler +- Inga XSS-risker i analysagenternas hantering av innehåll +- Robots.txt respekteras strikt +- Rate-limits respekteras strikt +- Alla anrop är idempotent och kan avbrytas säkert +``` + +### 14.3 Driftsäkerhet + +``` +- Varje agent kan starta om utan förlust (checkpoint var 5 minut) +- Agent-fel försöker maximalt 3 gånger med exponential backoff +- Övervakning av alla agent-ögon (hjärtslag + loggning) +- Fel i en agent påverkar inte andra (isolation) +``` + +--- + +## Anhang + +### A. Referensstrukturer + +- WCAG 2.2 AA/AAA för tillgänglighet +- RFC 9110 för HTTP +- OpenAPI 3.1 för API-kontrakt +- JSON Schema Draft 2020-12 för data-schema +- CSS Box Model specifikation för layout +- Material Design / Carbon Design System för komponentmönster + +### B. Utvecklingslogik + +| Vers | Datum | Beskrivning | +|---|---|---| +| 0.1.0 | 2026-XX-XX | Initial specifikation | + +### C. Offentliga beslut + +| ID | Beslut | Status | +|---|---|---| +| DEC-001 | C0PY ska producera maskinläsbar digital tvilling | Fastställd | +| DEC-002 | Allt infångning ska vara automatiskt via AI-agenter | Fastställd | +| DEC-003 | Utdataformat ska vara JSON + mediafiler | Fastställd | +| DEC-004 | Tillgänglighet ska verifieras i varje produktion | Pågående | +| DEC-005 | Agent-arkitektur ska vara parallell och isolerad | Fastställd | + +--- + +*Denna specifikation är en levande dokument och uppdateras löpande baserat på produktionsfunn och brukaranmälningar.*