Skip to content

Base MiniKit Docs Revamp #200

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

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Base MiniKit Docs Revamp #200

wants to merge 1 commit into from

Conversation

cturakhia-cb
Copy link

PR: Base MiniKit Docs Revamp — Comprehensive Change List

Navigation and IA

  • Updated docs/docs.json (Base App tab):
    • New pillar groups: Quick Start, Design & UX Standards, Performance & Assets, Quality Bar & Publishing, Growth & Analytics, Supporting Guides, Chat Agents
    • Added base-app/miniapps/manifest to Quick Start

New pages (Base App)

  • Quality Bar & Publishing

    • docs/base-app/quality/checklist.mdx: Mandatory Quality Bar checklist
    • docs/base-app/quality/getting-featured.mdx: Featuring criteria and process
    • docs/base-app/quality/submission-workflow.mdx: Submission guide
    • docs/base-app/quality/validation.mdx: Local and CI validation instructions

  • Design & UX Standards

    • docs/base-app/design/principles.mdx: HIG-inspired principles for webview
    • docs/base-app/design/ui-patterns.mdx: Copy-paste patterns (first-run, skeletons, optimistic UI, toast vs modal)
    • docs/base-app/design/accessibility.mdx: Safe areas, motion, semantics, contrast
    • docs/base-app/design/figma-ui-kit.mdx: Figma kit (placeholder link)

  • Performance & Assets

    • docs/base-app/performance/budgets.mdx: Budgets (TTI, TBT, CLS, payload caps) + optimization snippets
    • docs/base-app/performance/asset-specifications.mdx: Unified spec with sizes/bytes + server/CDN guidance
    • docs/base-app/performance/optimization-techniques.mdx: Practical recipes (preload, responsive images, caching)

  • Supporting Guides

    • docs/base-app/guides/authentication.mdx: Guest‑first patterns; browse-first vs action-gated flows
    • docs/base-app/guides/language-tone.mdx: Copy rules (ban jargon, outcome‑oriented CTAs)
    • docs/base-app/guides/error-handling.mdx: Error taxonomy and UX patterns
    • docs/base-app/guides/templates-starters.mdx: Starters overview + local usage

  • Growth & Analytics

    • docs/base-app/growth/event-schema.mdx: Recommended events (MINI_APP_OPEN, TX_SUCCESS, etc.)
    • docs/base-app/growth/analytics-integration.mdx: PostHog/Segment examples
    • docs/base-app/growth/distribution-categories.mdx: Category guidance and dos/don’ts

  • Quick Start adjunct

    • docs/base-app/miniapps/manifest.mdx: Manifest schema with explicit byte caps

New tooling

  • Local CLI: tools/minikit-cli
    • bin/mini-kit.mjs
    • Commands:
      • lint-copy [path]: Scans for banned terms, ignores code fences/inline code, prints suggestions
      • validate-assets [path]: Validates dimensions/byte caps for icon/splash/hero/OG
      • doctor [path]: Runs copy + assets checks
      • scaffold <name> --template=... --immediate-auth=true|false: Creates starter skeletons (browse-first, action-gated)
  • Repo config: minikit.config.json
    • Banned terms + suggestions
    • Asset caps (icon/splash/hero/OG)
    • Copy-lint excludes for guidance/design/intro pages
  • CI: .github/workflows/mini-kit.yml → runs mini-kit doctor on PRs
  • Submissions: .github/ISSUE_TEMPLATE/miniapp-featuring-request.md (Featuring request template)

Starter templates (local)

  • Added under starters/:
    • starters/browse-first: Guest‑first browse value → optional personalize → gate actions
    • starters/action-gated: Value-first screen; optional immediate auth in scaffold
    • starters/game-loop: Daily streak mechanic (customized src/App.tsx)
  • Each starter includes: index.html, src/main.tsx, src/App.tsx, package.json, README.md
  • Docs link: docs/base-app/guides/templates-starters.mdx explains local run

Notable edits

  • Placeholder Figma link set in figma-ui-kit.mdx
  • Quality Bar and Featuring criteria emphasize guest-first, performance budgets, and copy rules

Follow-ups (not in this PR)

  • Replace Figma placeholder with real link/assets
  • Promote starters to dedicated repos and link from docs
  • Add Lighthouse mobile harness to CI
  • Add minimal CSS tokens to starters for smoother DX
  • Add page for “Quality Lead & Office Hours” and link across Quality Bar/Submission

@cturakhia-cb
docs(minikit): restructure IA; add Quality Bar, Design, Performance, …
edac405 
…Growth pillars; add manifest doc; add starters; introduce mini-kit CLI (lint-copy, validate-assets, doctor, scaffold); add CI workflow and issue template; update templates/starters guide; add TASKS.md
@cb-heimdall
Copy link
Collaborator

🟡 Heimdall Review Status

Requirement Status More Info
Reviews 🟡 0/2
Denominator calculation
Show calculation
1 if user is bot 0
1 if user is external 0
2 if repo is sensitive 0
From .codeflow.yml 1
Additional review requirements
Show calculation
Max 0
0
From CODEOWNERS 0
Global minimum 0
Max 1
1
1 if commit is unverified 1
Sum 2

github-advanced-security[bot]
github-advanced-security bot found potential problems Aug 12, 2025
View reviewed changes
.github/workflows/mini-kit.yml
Comment on lines +11 to +20
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "18"
- name: Install CLI deps
run: npm ci --prefix tools/minikit-cli || npm install --prefix tools/minikit-cli
- name: Run doctor (Base App only)
run: node tools/minikit-cli/bin/mini-kit.mjs doctor docs/base-app

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}

Copilot Autofix

AI 10 days ago

To fix the problem, add a permissions block to the workflow to explicitly set the minimum required permissions for the GITHUB_TOKEN. Since the workflow appears to only check out code and run a CLI tool, it likely only needs read access to repository contents. The best way to fix this is to add permissions: contents: read at the top level of the workflow file, just below the name key and above the on key. This will apply the permission restriction to all jobs in the workflow. No other changes are needed.

Suggested changeset 1
.github/workflows/mini-kit.yml

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/.github/workflows/mini-kit.yml b/.github/workflows/mini-kit.yml
--- a/.github/workflows/mini-kit.yml
+++ b/.github/workflows/mini-kit.yml
@@ -1,3 +1,5 @@
+permissions:
+  contents: read
 name: MiniKit Doctor
 on:
   pull_request:
EOF
@@ -1,3 +1,5 @@
permissions:
contents: read
name: MiniKit Doctor
on:
pull_request:
Copilot is powered by AI and may make mistakes. Always verify output.
@dgca dgca marked this pull request as ready for review August 21, 2025 04:13
dgca
dgca reviewed Aug 21, 2025
View reviewed changes
.github/workflows/mini-kit.yml
@@ -0,0 +1,20 @@
name: MiniKit Doctor
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Could we scale this PR back to just the docs update for now? There's a lot going on in this action and I don't think it's currently running, so it's also hard to verify.

I'd also ask that we get rid of the starters/* folder, since we have templates and examples in the onchainkit repo. We've spread that sort of thing around in the past, and IMO it'd be nice to keep it it one place. The onchainkit repo makes the most sense to me, as we run tests against the templates when we make changes to OnchainKit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dgca dgca dgca left review comments

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@cturakhia-cb @cb-heimdall @dgca