Skip to content
opsinjs
Edit this page

Patterns

Consent and permissions

Ask for one permission at the moment it is needed, record what was agreed, and make refusing and withdrawing as easy as agreeing.

Consent is specific, informed, freely given, and withdrawable as easily as it was granted. A prompt that hides withdrawal in a settings sub-page is a subscription, not consent. Consent and privacy holds the doctrine.

When to use it

Use it whenever the product wants something it cannot take: health data from the device, notifications, sharing a record with a clinician, or a secondary use such as research.

Do not use it when:

  • The screen cannot exist without the permission. Say what it needs and let the reader leave, because a prompt with one real option is not a choice.
  • You are telling the reader what you already hold. That is Result disclosure.
  • It is a legal notice with no choice. Accepting terms is not consent to processing.
  • A question could disclose self-harm, abuse or a diagnosis. That is a distinct flow. See High-stakes moments.
Not written yet.

A pattern for disclosure inside a questionnaire and for crisis signposting. It needs clinical review, not only design.

How it works

  1. Ask at the moment of need, from the surface that needs it. Never ask at first launch.
  2. Explain in your own sheet first: what is collected, what it is for, who else sees it, how long it is kept, and what still works without it.
  3. Trigger the operating system's dialog only after the reader agrees to yours, because most platforms cannot re-ask after a refusal. Never style your sheet to look like that dialog.
  4. Ask one scope per sheet, with nothing pre-ticked. Three permissions are three sheets, each asked when it becomes useful.
  5. Record what was granted, when, by whom, and which version of the wording the reader saw.
  6. Deliver what the grant bought at once. After a refusal, keep the degraded but working surface, and re-offer only where it is needed.
  7. Put withdrawal at the same depth as agreement. It takes effect immediately and says what happens to data already shared, because revoked and deleted are different.

Re-ask when the scope or the wording changes, never on a timer.

Components

  • ConsentSheet asks one question, with refusing exactly as easy as agreeing.
  • Sheet is the surface ConsentSheet extends.
  • Term explains any legal or clinical word inline.
  • DisclaimerNote says what this consent does not cover.
  • EmptyState is the declined outcome, saying what still works and the way back.

Ask before collecting

import { ConsentSheet } from "@/components/ui/consent-sheet"
<ConsentSheet
  open={open}
  onOpenChange={setOpen}
  consentId="example-consent"
  textVersion={copy.version}
  heading={copy.question}
  purpose={copy.purpose}
  scope={copy.scope}
  withdrawalPath={copy.withdrawal}
  acceptLabel={copy.accept}
  declineLabel={copy.decline}
  onDecision={store}
/>
  • opsinjs ships no consent wording. Every string is a prop, and scope takes three sentences: collected, sharedWith and retention.
  • If any required string is missing or blank, the sheet refuses to ask and draws no controls.
  • onDecision fires only when a control is pressed. Escape, the scrim, a drag or Close call nothing, so a dismissal is never stored as an answer.
  • Store the ConsentDecision it returns: granted, at, consentId, textVersion and scope.
  • Pass consequenceOfDeclining whenever refusing costs the reader something.
Theme
Density
Text
Status
Accent theme
Accent
consent-sheet-two-questions-two-sheets · base base · style base-lyraOpen under the product theme
consent-sheet-two-questions-two-sheets.tsx
"use client"

import { useEffect, useRef, useState } from "react"

import { Button } from "@/components/ui/button"
import { ConsentSheet } from "@/components/ui/consent-sheet"

const FIRST_SCOPE = {
  collected: "Placeholder for what the first question collects.",
  sharedWith: "Placeholder for who can see it.",
  retention: "Placeholder for how long it is kept.",
}

const SECOND_SCOPE = {
  collected: "Placeholder for what the second question collects. This is a different thing.",
  sharedWith: "Placeholder for who can see it. This is a different recipient.",
  retention: "Placeholder for how long it is kept. This is a different period.",
}

export default function ConsentSheetTwoQuestionsTwoSheets() {
  const [asking, setAsking] = useState<"none" | "first" | "second">("none")
  const [answers, setAnswers] = useState<Record<string, string>>({})
  /* A sheet opened by a control returns focus to that control on its own. This
     one cannot, because by the time the last sheet closes the reader may have
     been through two of them and nothing they focused opened the second. So the
     return is written out. A counter rather than a boolean, because the reader
     can go through this more than once and a flag already `true` would not
     re-run the effect. */
  const triggerRef = useRef<HTMLDivElement>(null)
  const [returns, setReturns] = useState(0)
  /* Whether the first sheet closed because it was answered rather than because
     the reader left. It is a ref and not state, because the only reader of it is
     the first sheet's `onOpenChange`, which must not trigger a render of its own,
     and because it has to be set inside an event handler and read in the same
     handler without a re-render between the two. */
  const answeredRef = useRef(false)

  useEffect(() => {
    if (returns === 0) return
    triggerRef.current?.querySelector("button")?.focus()
  }, [returns])

  return (
    <div className="flex w-full flex-col items-center gap-opsin-4 p-opsin-4">
      <p className="m-0 max-w-sm text-center text-opsin-footnote text-muted-foreground">
        Two separate questions, asked one after the other. Answer them
        differently. The point of asking twice is that the two answers do not
        have to match.
      </p>

      {/* The trigger is read out of a wrapper rather than through a `ref` on
          Button, because `ButtonProps` omits `ref`: it extends the element's
          HTML attributes, and `ref` lives on `RefAttributes`. ConsentSheet
          reads its decision controls out of a wrapper for the same reason. */}
      <div ref={triggerRef}>
        <Button onClick={() => setAsking("first")}>Ask both example questions</Button>
      </div>

      <ul className="m-0 flex w-full max-w-md list-none flex-col gap-opsin-1 p-0 text-opsin-caption1 text-muted-foreground">
        {Object.keys(answers).length === 0 ? (
          <li>No answers yet.</li>
        ) : (
          Object.entries(answers).map(([id, verdict]) => (
            <li key={id} className="wrap-break-word">
              {id}: {verdict}
            </li>
          ))
        )}
      </ul>

      <ConsentSheet
        open={asking === "first"}
        onOpenChange={(nextOpen) => {
          if (nextOpen) return
          /* A close without an answer is not an answer, and it is not
             permission to ask the next thing either, so the reader is returned
             to the page. Telling "closed because it was answered" from "closed
             because the reader left" must not go through a state updater:
             React runs an updater twice in development StrictMode, so a
             `setReturns` called from inside one would count every dismissal
             twice. The answered case is recorded in a ref instead. Pressing a
             control runs `onDecision` first, which sets `answeredRef` and then
             `asking` to "second", thereby closing this sheet and firing
             `onOpenChange(false)` with the ref already true, so this handler
             consumes the flag and skips the return. A close the reader drove
             leaves the ref false and returns them to the page. A reader who
             wants question two can press the trigger again; in a real product
             it would be asked at the moment it became relevant. */
          if (answeredRef.current) {
            answeredRef.current = false
            return
          }
          setAsking("none")
          setReturns((count) => count + 1)
        }}
        consentId="example-consent-first"
        textVersion="example-wording-0"
        heading="Placeholder question one. Is this the first example thing?"
        purpose="Placeholder for the first purpose. In a product this sentence says what the reader gets."
        scope={FIRST_SCOPE}
        withdrawalPath="Placeholder for where a reader changes this first decision later."
        acceptLabel="Yes, to the first example thing"
        declineLabel="No, not the first example thing"
        onDecision={(decision) => {
          setAnswers((current) => ({
            ...current,
            [decision.consentId]: decision.granted ? "granted" : "declined",
          }))
          /* Record that this close is an answer before opening the next sheet,
             so the `onOpenChange` this triggers does not treat it as the reader
             leaving and does not return focus while the second sheet is opening. */
          answeredRef.current = true
          setAsking("second")
        }}
      />

      <ConsentSheet
        open={asking === "second"}
        onOpenChange={(nextOpen) => {
          if (nextOpen) return
          setAsking("none")
          setReturns((count) => count + 1)
        }}
        consentId="example-consent-second"
        textVersion="example-wording-0"
        heading="Placeholder question two. Is this the second example thing?"
        purpose="Placeholder for the second purpose, which is a different purpose and therefore a different question."
        scope={SECOND_SCOPE}
        withdrawalPath="Placeholder for where a reader changes this second decision later."
        consequenceOfDeclining="Placeholder for what a reader loses by saying no to this one. It is stated here, before they choose, and never raised as a confirmation afterwards."
        acceptLabel="Yes, to the second example thing"
        declineLabel="No, not the second example thing"
        onDecision={(decision) => {
          setAnswers((current) => ({
            ...current,
            [decision.consentId]: decision.granted ? "granted" : "declined",
          }))
          setAsking("none")
          setReturns((count) => count + 1)
        }}
      />
    </div>
  )
}

Example

Viewport width
Theme
Accent theme
Accent

NOT IMPLEMENTED. The opsinjs component `consent-flow` does not exist in any released version of opsinjs. There is no package to install, no module to import and no props interface to generate code against. Everything on this page is a specification of intended behaviour and may change without notice. Do not write code against it.

consent-flow is not built yet

This frame will embed /view/base/base-lyra/screen/consent-flow?mode=light, which renders under the product theme rather than the documentation chrome. There is nothing at that address yet.

PlannedRoadmapWhat “planned” means

Phone · 390px · /view/base/base-lyra/screen/consent-flow?mode=light

The whole-screen flow is not built yet, so the frame shows only its placeholder. The ConsentSheet example above is the shipped specimen.

Content

  • Describe the consequence, not the mechanism: who can see what, for how long, and how to stop it. "Enable data sharing to unlock the full experience" says none of that.
  • Both labels name an outcome. Never label the decline control "not now" when it means no. ConsentSheet warns about it in development.
  • Never make refusal sound reckless, and never write "by continuing you agree".

Accessibility

  • The explanation precedes the two controls in the DOM, so a screen reader meets the question first.
  • Both answers are one component used twice: the same size, contrast and target, adjacent in the tab order. Check in greyscale, and at 200% text, where both must stay visible together.
  • Focus enters the sheet, Escape closes it with no answer given, and focus returns to the opener.
  • Nothing times out, auto-advances or dismisses itself.