Documentation system

A learning path for explainable permissions.

The Accessly docs should help a React developer understand the model, install the package, build the first permission check, and find any API without digging through generated reference pages.

5 min

Understand the product

1 command

Install from npm

1 check

Render gated UI

Seconds

Find any API

Start

Install first

Installation stays short and direct. The default package manager is npm, with other package managers available as secondary tabs in implementation pages.

npm

$ npm install accessly

First success

Build one permission check

Quick Start should get to visible behavior quickly: provide an access model, render with Can, then explain the decision model only after the user has seen it work.

App.tsx

import { PermissionProvider, Can } from "accessly";

export function App() {
  return (
    <PermissionProvider
      access={{ permissions: ["users.create"] }}
    >
      <Can permission="users.create">
        <CreateUserButton />
      </Can>
    </PermissionProvider>
  );
}

Architecture

Complete documentation architecture

The structure separates learning, workflow, debugging, and reference material. That keeps beginner pages calm while still making each API searchable and directly addressable.

Start

4 pages

Overview

Getting Started

Installation

Quick Start

Learn

5 pages

Core Concepts

React APIs

Backend Adapters

Navigation

Debugging

Guides

2 pages

Use Cases

AI Prompts

Reference

3 pages

API Reference

FAQ

Known Limitations

Introduction

What is Accessly?

Accessly is a small React permission layer for rendering UI from an explainable access model.

It helps product UI ask clear permission questions.

It keeps permission checks close to the components that need them.

It returns decision details so denials are easier to debug.

Introduction

Why Accessly?

Accessly exists to make frontend permission logic consistent, inspectable, and easier to teach.

Avoid scattering string checks across the app.

Make permission behavior visible through decisions and debugging tools.

Keep backend authorization separate from frontend UI gating.

Core concept

AccessModel

AccessModel is the normalized shape Accessly reads when evaluating permissions.

It should be easy to build from your backend response.

It becomes the source of truth for components, hooks, and navigation filtering.

Docs should show roles, permissions, and feature flags in one compact model.

Core concept

PermissionProvider

The provider is the boundary that places the current access model into React context.

Use it near the app root or inside the authenticated app shell.

Keep backend loading outside the provider, then pass the normalized model in.

React APIs below the provider can read permissions without prop drilling.

Core concept

Permission Engine

The engine evaluates roles, permissions, and flags into one explainable result.

It should feel deterministic and easy to debug.

Every check should answer both whether access is allowed and why.

The docs should teach the matching order before advanced examples.

Core concept

AccessDecision

An AccessDecision is the result object that powers UI states and debugging.

Lead with allowed, denied, and fallback UI examples.

Explain matched values and checked source without overloading the first read.

Link directly to decision explanations and formatting utilities.

Core concept

Backend Adapters

Adapters let teams keep their backend shape while giving Accessly a consistent model.

Show the backend response before the normalized access model.

Explain when to write an adapter versus passing an access model directly.

Keep backend mapping examples task-oriented, not showcase-oriented.

React API

PermissionProvider

The React PermissionProvider wires a current AccessModel into the component tree.

Show where it belongs in a React or Next.js app.

Explain loading, empty, and authenticated states separately.

Link back to the core PermissionProvider concept for the mental model.

React API

Can

Can renders children when a permission, role, or feature flag is allowed.

Start with the smallest visible UI example.

Show fallback usage right after the basic example.

Link to useAccessDecision for custom states.

React API

Cannot

Cannot renders inverse access states without making product code harder to read.

Use it for empty states, upgrade prompts, and restricted messaging.

Warn against duplicating business logic outside Accessly.

Keep examples paired with the equivalent Can fallback pattern.

React API

ProtectedRoute

ProtectedRoute gates route-level UI while keeping the decision model inspectable.

Explain route protection as UI gating, not backend security.

Show fallback and redirect patterns separately.

Link back to PermissionProvider setup.

React hook

usePermission

usePermission gives custom components a small boolean permission check.

Use it when Can is not expressive enough for a component.

Keep the basic example shorter than the decision hook page.

Link to useAccessDecision for richer debugging states.

React hook

useAccessDecision

useAccessDecision returns the full explainable decision for a single check.

Teach this as the debugging-first hook.

Show denied UI, matched permissions, and checked source.

Link to formatDecision for readable output.

React hook

useAccessModel

useAccessModel exposes the current normalized model for advanced UI composition.

Reserve it for advanced components and developer tooling.

Warn against scattering manual permission parsing throughout the app.

Link to AccessModel and filterNavigation.

Backend adapter

createAdapter

createAdapter normalizes backend-specific permission payloads into an AccessModel.

Show input and output side by side.

Make validation and missing fields explicit.

Link to the Lab for testing real JSON responses.

Backend adapter

Built-in adapters

Built-in adapters should cover common backend response shapes without hiding the model.

Document supported shapes as comparisons.

Show when a custom adapter is clearer.

Keep adapter naming stable for search.

Backend adapter

Adapter patterns

Adapter patterns are small task guides for common backend integration problems.

Keep patterns inside docs, not as marketing showcases.

Each pattern should solve one backend mapping problem.

Always end with the normalized AccessModel.

Debugging

Decision explanations

Decision explanations help developers understand why a permission passed or failed.

Use small annotated examples instead of long prose.

Explain matched values, missing values, and checked sources.

Link every debugging concept back to the Lab.

Debugging

formatDecision

formatDecision turns a raw decision object into a readable developer message.

Show console, UI, and test output use cases.

Keep formatting separate from access evaluation.

Link to inspectAccess for deeper debugging.

Debugging

inspectAccess

inspectAccess should help developers inspect a model before debugging individual checks.

Teach it as a model-level debugging utility.

Show invalid, empty, and partially matched model states.

Link to backend adapters when model shape is the problem.

Reference

API Reference

The API Reference should be the fastest way to find exact names, signatures, and related pages.

Group APIs by component, hook, utility, adapter, and type.

Keep reference entries scannable and link back to learning pages.

Use badges and stable titles so search results are predictable.

Reference

FAQ

The FAQ should answer practical Accessly questions without becoming the primary docs.

Keep answers short and link to the canonical page.

Prioritize installation, SSR, backend shape, and debugging questions.

Avoid using FAQ as a dumping ground for missing guides.

Reference

Known Limitations

Known limitations should be direct, specific, and paired with recommended approaches.

Separate product limitations from security guidance.

Explain client-side gating clearly.

Keep this page easy to find from API and debugging pages.

Flow

Navigation flow

The main path is intentionally linear. It gives new readers a fast mental model before sending them into individual React APIs or backend adapter details.

What is Accessly?

Why Accessly?

Installation

Quick Start

AccessModel

PermissionProvider

Can

usePermission

AccessDecision

Decision explanations

Mental model

Core architecture

Diagrams should show how backend data becomes a decision. Each core concept page should teach one stage of this pipeline.

accessly-pipeline.txt

Backend response
  -> createAdapter()
  -> AccessModel
  -> PermissionProvider
  -> Permission Engine
  -> AccessDecision
  -> Can / hooks / navigation

AccessModel

The normalized shape Accessly evaluates.

Permission Engine

The matching layer that evaluates roles, flags, and permissions.

AccessDecision

The explainable result used by UI, hooks, and debugging tools.

Backend Adapters

The boundary that lets each app keep its own backend shape.

Template

Every docs page follows one shape

The template should make pages predictable without forcing every page to become long. Short reference pages can compress sections; learning pages can expand them.

Title

One sentence summary

Why this exists

Interactive example

Basic example

Advanced example

Common mistakes

Best practices

Related APIs

Patterns

Page types

Accessly needs three repeatable page patterns: concept pages for mental models, API pages for exact usage, and workflow pages for task completion.

Concept pages

Teach one mental model, show where it sits in the pipeline, then link to the APIs that use it.

AccessModelPermission EngineAccessDecision

API pages

Lead with usage, keep parameters scannable, then explain edge cases and debugging behavior.

CanuseAccessDecisionfilterNavigation

Workflow pages

Guide developers through a task from setup to a working result, with Lab links where behavior is inspectable.

InstallationQuick StartBackend Adapters

URL structure

Search depends on stable titles and predictable paths. These URLs are the current documentation routes for the release-ready docs set.

/docsDocumentation home

/docs/getting-startedGetting Started

/docs/installationInstallation

/docs/quick-startQuick Start

/docs/core-conceptsCore Concepts

/docs/react-apisReact APIs

/docs/backend-adaptersBackend Adapters

/docs/navigationNavigation

/docs/debuggingDebugging

/docs/use-casesUse Cases

/docs/aiAI Prompts

/docs/api-referenceAPI Reference

/docs/faqFAQ

/docs/known-limitationsKnown Limitations

Design

Documentation UI recommendations

The docs should feel like a premium developer product: quiet, readable, precise, and fast to scan.

Use one calm dark reading surface with subtle dividers and generous vertical rhythm.

Keep the article column narrow enough to read and the reference data wide enough to scan.

Use restrained badges for component, hook, utility, adapter, and debugging APIs.

Prefer short examples, callouts, diagrams, and comparison tables over long prose.

Make Lab links contextual so the docs feel interactive without becoming a dashboard.

Open Lab

Use the Lab as the interactive companion for decisions, adapters, and debugging pages.

Back Home

Return to the product overview and main Accessly workflow.

import { PermissionProvider, Can } from "accessly"; export function App() { return ( <PermissionProvider access={{ permissions: ["users.create"] }} > <Can permission="users.create"> <CreateUserButton /> </Can> </PermissionProvider> ); }