Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
74 changes: 74 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Working on TendUI-web

This repository is the Go website at https://tendui.com. It consumes the TendUI
library; it is not the library source. Read relevant code and tests before editing,
preserve unrelated work, and follow [CONTRIBUTING.md](CONTRIBUTING.md).

## Structure

- `main.go` wires the HTTP server, embedded assets and mounted library demos.
- `docs.go` registers guides, navigation and the sitemap. Guide bodies live in
`content/*.html` as Go HTML templates with a `body` definition.
- `docs.templ` renders the documentation shell. `site_header.templ` is shared by
home, docs, catalog and demos; preserve that single header and theme behavior.
- `static/` contains website CSS and brand assets. Preserve content-hashed asset
URLs, favicon coverage, canonical URLs and existing cache/security headers.
- `library-version.json`, `go.mod`, `go.sum` and `vendor/` record one exact library
dependency. Do not hand-edit vendor or ship local module replacements.
- Library changes belong in `Tend-Stack/TendUI`. To update an authorized dependency
from a clean library checkout, use `python3 tools/vendor-library.py /path/to/TendUI`
and commit all resulting metadata and vendor changes together.

## Product rules

- Use TendUI components and semantic HTML. Keep the public site usable without
JavaScript; do not add frontend build tools, remote fonts or runtime downloads.
- The browser test suite may use Node/npm; building and serving the site need Go
only. Read `go.mod` for Go and templ versions.
- Use the installed library API, not guessed props or examples from a newer tag.
Keep installation instructions pinned and accurate; do not silently upgrade.
- Preserve native forms/links, focus, labels, theme cookies, reduced motion and
narrow-screen layouts. Keep the shared header and 1920px maximum consistent.
- Demos are bounded examples, not production account creation or persistence.
Do not weaken origin validation or cookie protections to make a demo pass.
- Keep public documentation free of private infrastructure, credentials and local
workstation paths. Retain asset provenance and license notices.

## Commands and validation

Run from the repository root:

```sh
go run . # local server; PORT defaults to 8080
go test -race ./...
go vet ./...
```

For template edits, use the generator matching `go.mod`, run `templ fmt .` and
`templ generate`, and commit `.templ` and `_templ.go` together. Never hand-edit
generated output. Normal builds use the committed output and vendored modules.

For new guides, update `docs.go` and its navigation labels together; the sitemap
uses the guide registry. Add the route to the existing browser guide audit in
`tests/browser/site.spec.js`. HTTP tests already exercise each registered guide.
Check links and code samples, mobile containment and keyboard navigation.

Use focused checks while editing and CI for full verification. Follow
[CONTRIBUTING.md](CONTRIBUTING.md) for browser tooling. Store task artifacts under
ignored `tests/results/`; remove only owned disposable output and keep concise
failure evidence. Do not create duplicate environments or discard unrelated work.

## Delivery

- Submit focused PRs to GitHub `Tend-Stack/TendUI-web` main. MIT + DCO applies;
human contributors review and authorize their own sign-offs. Never fabricate
someone else's identity, certification or test results.
- A push to main can trigger Tend deployment. Publish only within the user's
authorized scope, preserve active work and existing data, and verify CI and
deployment separately. Do not add deployment credentials to this repository.
- Settings in `.github/settings/` are prepared configurations, not proof that
GitHub rules or a Project are active.
- Verify changed routes through the public domain after an authorized deployment;
check actual served content, not only a successful build status.
- Report what changed, tests actually run, live verification when applicable,
and remaining limitations. Do not claim a deployed result from a local test.
3 changes: 3 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Shared project instructions

@AGENTS.md
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ For your own last commit, use `git commit --amend --signoff`; coordinate with
reviewers before rewriting an already-pushed contribution branch. Maintainers do
not add missing contributor certifications on someone else's behalf.

Coding agents should read [AGENTS.md](AGENTS.md) for repository structure and
validation guidance; `CLAUDE.md` imports that same file.

AI-assisted contributions follow exactly the same rules: a human contributor
must understand, review and test the result and certify the right to submit it.
Identify significant generated material or reused sources in the PR description.
Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,3 +105,10 @@ sets a longer browser cache lifetime.
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, review and MIT + DCO sign-off.
Report vulnerabilities privately using [SECURITY.md](SECURITY.md); community
participation follows [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Coding agents

Repository contributors should read [AGENTS.md](AGENTS.md); `CLAUDE.md` imports
the same instructions for Claude Code. For applications using TendUI, see
[the coding-agent guide](https://tendui.com/docs/agents) and merge its suggested
section into your own project instructions.
51 changes: 51 additions & 0 deletions content/agents.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
{{define "body"}}
<h2>Give your agent the right starting point.</h2>
<p>TendUI works with coding agents just as it does with people: use the installed API, semantic HTML and your application's existing stack. Tell the agent whether you use plain HTML, Go's <code>html/template</code>, or Go with templ. HTMX is optional.</p>
<div class="doc-callout"><strong>Using TendUI or contributing to it?</strong><p>The instructions below are for your own application. To change the library or this website, use the repository instructions linked at the end of this page.</p></div>
<h2>1. Add context to your project</h2>
<p>Merge this section into <code>AGENTS.md</code> in your application root. Preserve your existing instructions and adapt the validation commands to your project. Installing a Go dependency does not install project instructions into your app.</p>
<pre tabindex="0" aria-label="TendUI application instructions"><code>## TendUI in this application

- Read go.mod (or the pinned CSS source) to identify the installed TendUI version.
Do not upgrade it or guess component props/classes to complete a task.
- Prefer semantic HTML and native browser controls. Do not add Node/npm, a CSS
build step, or client JavaScript solely to use TendUI.
- With Go, import github.com/Tend-Stack/TendUI/v2026 as package tendui.
Mount tendui.AssetHandler() at tendui.AssetPath without StripPrefix and link
tendui.StylesheetURL. CSS is embedded and ships inside the executable.
- With templ, use typed components from the /components package. Inspect the
installed API before writing props. Edit .templ files, regenerate with the
generator matching the application&#x27;s templ dependency, and commit generated Go.
- For plain HTML or html/template, serve the pinned stylesheet as a local asset;
keep existing escaping and server-side rendering. templ is optional.
- Applications own routes, validation, authentication, CSRF protection, sessions
and persistence. Never copy demo handlers as production security logic.
- HTMX attributes alone do not execute requests. Add the optional runtime only
when requested; keep native form/link fallbacks and correct fragment responses.
- Use documented --tendui-* tokens and data-theme=&quot;light&quot; or &quot;dark&quot;; omit the
theme attribute for system preference. Preserve labels, focus, keyboard access,
responsive layout, error messages and reduced-motion behavior.
- Run the application&#x27;s relevant tests and build. Check the page and stylesheet
routes and the requested user flow; report checks performed and limitations.</code></pre>
<p>Start from the <a href="/docs/install">Go and templ quickstart</a> or <a href="/docs/html">HTML and CSS guide</a>. Use the <a href="/catalog">catalog</a> to find a pattern, then check the source and props at your installed version; online examples may describe a newer release.</p>
<h2>2. Connect your coding tool</h2>
<h3>Codex</h3>
<p>Codex reads project <code>AGENTS.md</code> files. Keep the shared instructions in your project root and follow the <a href="https://learn.chatgpt.com/docs/agent-configuration/agents-md">official instruction-discovery guide</a> for directory scope and overrides.</p>
<h3>Claude Code</h3>
<p>Add this import to a neighboring <code>CLAUDE.md</code>, preserving existing content. Put the import on its own line outside a code fence in the actual file:</p>
<pre tabindex="0" aria-label="Claude Code shared instructions import"><code>@AGENTS.md</code></pre>
<p>The <a href="https://code.claude.com/docs/en/memory#import-additional-files">documented import mechanism</a> lets you maintain one shared policy, including in sessions that do not load <code>AGENTS.md</code> directly.</p>
<h3>Other tools</h3>
<p>Select this file in the tool's project-context settings or ask it explicitly to read it. Automatic discovery varies. Start a fresh session after setup and ask the agent to summarize the applicable instructions and installed TendUI version before editing.</p>
<p>Instruction files guide behavior. Tests, human review and tool permissions still matter; the files do not enforce permissions or guarantee correctness.</p>
<h2>3. Give it a concrete task</h2>
<blockquote><p>Read our project instructions and installed TendUI API. Add a labeled settings form using our existing stack and server routes. Preserve native submission, light/dark themes and keyboard behavior. Show the changed files, run relevant tests, and explain anything you could not verify. Do not add dependencies.</p></blockquote>
<p>Review the result in the browser, including keyboard focus, narrow screens and error states. Verify that the stylesheet loads and native interactions work with JavaScript disabled. If you intentionally enable HTMX, test both enhanced and ordinary requests.</p>
<h2>Contributing to TendUI itself</h2>
<ul>
<li><a href="https://github.com/Tend-Stack/TendUI/blob/main/AGENTS.md">Library agent instructions</a>: components, semantic CSS, generated code, API compatibility and validation.</li>
<li><a href="https://github.com/Tend-Stack/TendUI-web/blob/main/AGENTS.md">Website agent instructions</a>: guide routes, shared header, pinned dependencies and deployment verification.</li>
<li><a href="https://github.com/Tend-Stack/TendUI/blob/main/docs/agents.md">Application guidance in the repository</a>: a Markdown version of this setup.</li>
</ul>
<p>Both repositories include a <code>CLAUDE.md</code> import of their own <code>AGENTS.md</code>. AI-assisted contributions follow <a href="https://github.com/Tend-Stack/TendUI/blob/main/CONTRIBUTING.md">MIT + DCO contribution rules</a>: a human reviews, tests and authorizes their own sign-off.</p>
{{end}}
1 change: 1 addition & 0 deletions content/overview.html
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,6 @@ <h2>What your application supplies</h2>
<h2>Three packages</h2>
<div class="table-scroll" tabindex="0" role="region" aria-label="Package reference"><table><caption>Production package responsibilities</caption><thead><tr><th>Import suffix</th><th>Responsibility</th></tr></thead><tbody><tr><td><code>tendui</code> (module root)</td><td>Embedded stylesheet and asset handler.</td></tr><tr><td><code>/components</code></td><td>Typed templ components and appearance settings.</td></tr><tr><td><code>/render</code></td><td>Full-page and fragment HTTP responses.</td></tr></tbody></table></div>
<p>The asset and render helpers use the Go standard library. Components depend on templ. Generated Go is included, so consuming the library does not require its generator; authoring your own templ pages does.</p>
<h2>Working with a coding agent</h2><p>Give Codex, Claude Code or another assistant <a href="/docs/agents">project instructions for TendUI</a>, including the installed API, native behavior and validation steps.</p>
<h2>Explore by doing</h2><p>Use the <a href="/playground">playground</a> to test states and appearance, the <a href="/examples">application examples</a> to see complete flows, and the <a href="/catalog">component reference</a> to take a recipe into your own app.</p>
{{end}}
3 changes: 2 additions & 1 deletion docs.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ var guides = []guide{
{"/docs", "Build something thoughtful.", "A practical guide to semantic interfaces with Go, templ, and optional HTMX.", "overview"},
{"/docs/install", "From module to interface.", "Install TendUI, serve its embedded CSS, and render your first page.", "install"},
{"/docs/html", "Start with HTML. Add your stack.", "Use TendUI with two static files and no build tools.", "html"},
{"/docs/agents", "Build with a coding agent.", "Give Codex, Claude Code and other tools practical TendUI project instructions.", "agents"},
{"/docs/theming", "Make it feel like yours.", "Choose a color mode, compose appearance settings, or override the tokens.", "theming"},
{"/docs/forms", "Forms that work with the browser.", "Native submission first. Validation and persistence belong to your application.", "forms"},
{"/docs/htmx", "Enhance a working page.", "Use optional HTMX attributes with explicit full-page and fragment responses.", "htmx"},
Expand All @@ -37,7 +38,7 @@ func registerDocs(mux *http.ServeMux) {
}
var buf bytes.Buffer
navigation := make([]components.NavItem, 0, len(guides)+1)
labels := []string{"Introduction", "Installation", "HTML & CSS", "Appearance", "Forms & validation", "HTMX", "Accessibility", "Deployment", "Examples"}
labels := []string{"Introduction", "Installation", "HTML & CSS", "Coding agents", "Appearance", "Forms & validation", "HTMX", "Accessibility", "Deployment", "Examples"}
for i, entry := range guides {
navigation = append(navigation, components.NavItem{Label: labels[i], Href: entry.Path, Current: entry.Path == g.Path})
}
Expand Down
2 changes: 1 addition & 1 deletion tests/browser/site.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ async function siteNavigation(page) {

test('guides, examples, and homepage remain accessible and contained', async ({ page }, testInfo) => {
test.setTimeout(180000);
for (const route of ['/', '/docs', '/docs/install', '/docs/html', '/docs/theming', '/docs/forms', '/docs/htmx', '/docs/accessibility', '/docs/deploy', '/examples']) {
for (const route of ['/', '/docs', '/docs/install', '/docs/html', '/docs/agents', '/docs/theming', '/docs/forms', '/docs/htmx', '/docs/accessibility', '/docs/deploy', '/examples']) {
const response = await page.goto(route);
expect(response.status()).toBe(200);
await expect(page.locator('main')).toHaveCount(1);
Expand Down